{"id":13517024,"url":"https://github.com/uploadcare/react-widget","last_synced_at":"2025-04-07T10:19:33.329Z","repository":{"id":38360522,"uuid":"59756927","full_name":"uploadcare/react-widget","owner":"uploadcare","description":"Uploadcare React Widget","archived":false,"fork":false,"pushed_at":"2024-08-27T10:04:30.000Z","size":4796,"stargazers_count":85,"open_issues_count":23,"forks_count":18,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-31T09:03:23.143Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uploadcare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-26T14:28:25.000Z","updated_at":"2024-11-03T15:54:26.000Z","dependencies_parsed_at":"2024-01-13T19:26:37.386Z","dependency_job_id":"1d5c864c-4055-4879-8d06-24e85c7912c2","html_url":"https://github.com/uploadcare/react-widget","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Freact-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Freact-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Freact-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Freact-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uploadcare","download_url":"https://codeload.github.com/uploadcare/react-widget/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247631834,"owners_count":20970069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T05:01:28.670Z","updated_at":"2025-04-07T10:19:33.311Z","avatar_url":"https://github.com/uploadcare.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# React Wrapper for jQuery File Uploader\n\n## ⚠️ Notice: File Uploader Option\n\n**This uploading wrapper remains fully functional and can be a great fit for your projects, especially if you have specific needs for jQuery. However, we recommend exploring our new [React File Uploader](https://github.com/uploadcare/react-components/tree/main/packages/react-uploader?tab=readme) to access the latest features and improvements.**\n\n---\n\n\u003ca href=\"https://uploadcare.com/?utm_source=github\u0026utm_campaign=react-widget\"\u003e\n  \u003cimg align=\"right\" width=\"56\" height=\"56\"\n    src=\"https://ucarecdn.com/1cc871de-5d82-442d-b4d6-aa2e35966879/-/resize/112x112/-/quality/lightest/logocircle2x.png\"\n    alt=\"\"\u003e\n\u003c/a\u003e\n\nThis React component helps you integrate [Uploadcare jQuery File Uploader][uc-feature-widget]\ninto your React app natively; props management and lazy loading are bundled.\n\nThe component allows users to upload files from any file system and device, social media,\ncloud storage, and more. Best-in-class for image upload.\nAll that without any backend code that’s usually required to handle uploads.\n\n#### [Read Uploadcare + React Integration Guide][react-guide]\n\n[![Build Status][build-img]][build-link]\n[![NPM version][npm-img]][npm-link]\n\n* [Install](#install)\n* [Usage](#usage)\n* [Available bundles](#available-bundles)\n* [Configuration](#configuration)\n  * [`Widget` component configuration](#widget-component-configuration)\n  * [`Panel` component configuration](#panel-component-configuration)\n  * [Widget configuration](#widget-configuration)\n* [Security issues](#security-issues)\n* [Feedback](#feedback)\n\n## Install\n\n```\nnpm i @uploadcare/react-widget\n```\n\n## Usage\n\n```jsx\nimport { Widget } from \"@uploadcare/react-widget\";\n\n\u003cWidget publicKey=\"YOUR_PUBLIC_KEY\" /\u003e;\n```\n\nor\n\n```jsx\nimport { Panel } from \"@uploadcare/react-widget\";\n\n\u003cPanel publicKey=\"YOUR_PUBLIC_KEY\" /\u003e;\n```\n\n* [Basic usage example on CodeSandbox][sandbox-props]\n* [Gatsby basic usage example on CodeSandbox][sandbox-gatsby]\n\nTo use this component, get an **API key** from your Uploadcare project.\n\nUploadcare account provides services for file uploads, transformations, CDN\ndelivery, as well as APIs. After [signing up][uc-sign-up], you'll see Dashboard\nwhere you can manage projects. Each Project is identified by its *public key*.\nReplace `YOUR_PUBLIC_KEY` with your project’s Public API Key and you are all\nset.\n\nYou can refer to our [integration guide][react-guide] for more details.\n\n## Available bundles\nBy default, npm and other package managers import the full (all locales) CommonJS or ESM bundle.\n\nTo reduce your bundle size, you can also import one of the following:\n* The english-only bundle (saves ~27% in bundle size) as `@uploadcare/react-widget/en`\n* The minified all-locales bundle (saves ~44% in bundle size) as `@uploadcare/react-widget/min`\n* The minified english-only bundle (saves ~60% in bundle size) as `@uploadcare/react-widget/en-min`\n\n## Configuration\n\n### `Widget` component configuration\n\n#### `value: string[] | string | JQuery.Deferred | JQuery.Deferred[]`\n\nSet an array of [file UUID][uc-docs-files]/[group UUID][uc-docs-groups]/[CDN URL][delivery-docs]/[File Instance][uc-docs-widget-api-file-instance]/[Group Instance][uc-docs-widget-api-group-instance]\nas a value.\n\n```jsx\n\u003cWidget value='9dd2f080-cc52-442d-aa06-1d9eec7f40d1' /\u003e\n\u003cWidget value='9dd2f080-cc52-442d-aa06-1d9eec7f40d1~12' /\u003e\n\u003cWidget value={[\n  '9dd2f080-cc52-442d-aa06-1d9eec7f40d1',\n  'https://ucarecdn.com/fdfe4e67-f747-4993-91f5-be21d6d3c1a6/',\n  '9ef9af26-7356-4428-b69c-1b920f947989~2'\n]} /\u003e\n```\n\n\u003cbr\u003e\n\n#### `onChange: (fileInfo: FileInfo) =\u003e void`\n\nSet a function to be called after **a file is uploaded and ready**.\n\n* [FileInfo object description][api-refs-props]\n* [Example][sandbox-on-change]\n\n\u003cbr\u003e\n\n#### `onFileSelect: (fileInfo: FileInfo | FilesInfo | null) =\u003e void`\n\nSet a function to be called after **a new file is selected**.\n\n* [FileInfo object description][api-refs-props]\n* [FilesInfo object description][multi-type-desc]\n* [Example][sandbox-on-file-select]\n\n\u003cbr\u003e\n\n#### `onDialogOpen: (dialog: DialogApi) =\u003e void`\n\nSet a function to be called after **dialog is opened**.\n\n* [DialogApi object description][api-refs-dialog]\n\n\u003cbr\u003e\n\n#### `onDialogClose: (objs: FileInfo | FilesInfo | null) =\u003e void`\n\nSet a function to be called after **dialog is closed**.\n\n* [FileInfo object description][api-refs-props]\n* [FilesInfo object description][multi-type-desc]\n\n\u003cbr\u003e\n\n#### `onTabChange: (tabName: string) =\u003e void`\n\nSet a function to be called after **tab is changed**.\n\n\u003cbr\u003e\n\n#### `metadata: (metadata: Record\u003cstring, string\u003e)`\n\nThe option can be used to set metadata object associated with the uploaded file.\n\nNote that metadata supports `string` values only, any non-string value will be converted to `string`, including `boolean`, `number`, `null` and `undefined`.\n\n**WARNING**: If this option is specified, option `metadataCallback` will be overridden (without merging).\nThis is opposite from the uploadcare-widget's behavior.\n\nSee [Metadata docs][uc-docs-metadata] for details.\n\n\u003cbr\u003e\n\n#### `metadataCallback: () =\u003e Record\u003cstring, string\u003e`\n\nDefines the function that specifies the actual metadata object a file uploader should use to associate with the uploaded file. It's helpful in the case of dynamic metadata object.\n\nNote that metadata supports `string` values only, any non-string value will be converted to `string`, including `boolean`, `number`, `null` and `undefined`.\n\nSee [Metadata docs][uc-docs-metadata] for details.\n\n\u003cbr\u003e\n\n#### `customTabs: {[key: string]: CustomTabConstructor}`\n\nAdd **custom tabs** for a widget.\n\n```jsx\nfunction myTab(container, button, dialogApi, settings, name, uploadcare) {\n  ...\n}\n\n\u003cWidget customTabs={{ tabname: myTab }} /\u003e\n```\n\nSince custom tabs are global internally, any local property change will affect all the widget instances.\nSo we're highly recommend not to redefine tab constructors and not to have different constructors under the same name.\n\nNote that we added the fifth argument to the custom tab constructor — an\n`uploadcare` object. The widget is lazily-loaded, so you don’t have to import\n`uploadcare-widget` separately for your custom tab.\n\nRemember that you also need to include your custom tab in the `tabs` prop to\nmake it work:\n\n```jsx\n\u003cWidget customTabs={{ tabname: myTab }} tabs='tabname' /\u003e\n```\n\n* [Custom tabs docs][custom-tabs-docs]\n* [Example][sandbox-custom-tab]\n\n\u003cbr\u003e\n\n#### Add [Image Editor][uc-docs-image-editor]\n\n1. Install `uploadcare-widget-tab-effects` package\n\n```bash\nnpm i uploadcare-widget-tab-effects\n```\n\n2. Import one of the bundles:\n\n  * `uploadcare-widget-tab-effects/react` for all-locales bundle\n  * `uploadcare-widget-tab-effects/react-en` for english-only bundle\n\n```js\nimport effects from 'uploadcare-widget-tab-effects/react'\n// or\n// import effects from 'uploadcare-widget-tab-effects/react-en'\n```\n\n3. Pass the `effects` object to the `customTabs` prop:\n\n```jsx\n\u003cWidget previewStep customTabs={{ preview: effects }} /\u003e\n```\n\n\u003cbr\u003e\n\n#### `validators: Validator[]`\n\nSet **validators** for a widget. Validator is a JavaScript function that\nreceives a `fileInfo` object for each uploaded file and throws an exception if\nthat file doesn't meet validation requirements.\n\n```jsx\nconst fileTypeLimit = (allowedFileTypes: string) =\u003e {\n  const types = allowedFileTypes.split(' ')\n\n  return function(fileInfo: FileInfo) {\n    if (fileInfo.name === null) {\n      return\n    }\n    const extension = fileInfo.name.split('.').pop()\n\n    if (extension \u0026\u0026 !types.includes(extension)) {\n      throw new Error('fileType')\n    }\n  }\n}\n\nconst validators = [fileTypeLimit('mp3 avi mp4')];\n\n\u003cWidget validators={validators} /\u003e\n```\n\n* [Validator object description][api-refs-validation]\n* [FileInfo object description][api-refs-props]\n* [Example][sandbox-validators]\n\n\u003cbr\u003e\n\n#### `preloader: ComponentType`\n\nSet a custom **preloader**. A preloader component shows up when the widget\nis being loaded.\n\n\u003cbr\u003e\n\n#### `ref: widgetApiRef`\n\nDefine a reference object to address the Widget API wrapper. Use it to access\nthese methods: `value`, `openDialog`, `reloadInfo` and `getInput`.\n\n1. `value()` is the alias for [`widget.value()`][uc-docs-widget-single-file-value]\n2. `openDialog()` is the alias for [`widget.openDialog()`][uc-docs-widget-open-dialog]\n3. `reloadIngo()` is the alias for [`widget.reloadInfo()`][uc-docs-widget-reload-info]\n4. `getInput()` returns widget's input element instance.\n\nExample:\n\n```jsx\nconst Example = () =\u003e {\n const widgetApi = useRef();\n return (\n   \u003c\u003e\n     \u003cbutton onClick={() =\u003e widgetApi.current.openDialog()}\u003e\n       Click me\n     \u003c/button\u003e\n     \u003cWidget ref={widgetApi} publicKey=“demopublickey” /\u003e\n   \u003c/\u003e\n );\n};\n```\n\n* [Widget API reference][uc-docs-widget-js-api]\n* [Example][sandbox-ref]\n\n\u003cbr\u003e\n\n#### `tabsCss: string`\n\nOptional. Define a custom CSS for tabs opened in iframes (e.g., Facebook,\nInstagram, etc.). It can be a CSS string or an absolute URL to a CSS file.\n\n```jsx\n// Via URL\n\u003cWidget tabs=\"facebook\" tabsCss=\"https://site.com/styles/uc.tabs.css\"/\u003e\n\n// Via plain CSS\n\u003cWidget tabs=\"facebook\" tabsCss=\".source-facebook { background: #1877F2; }\"/\u003e\n```\n\nNote that all iframe tabs are opened via HTTPS, so linked CSS files should also\nbe available over HTTPS.\n\n* [Widget styling docs][uc-docs-widget-styling]\n\n\u003cbr\u003e\n\n### `Panel` component configuration\n\n#### `value: string[] | string | JQuery.Deferred | JQuery.Deferred[]`\n\nSet an array of [file UUID][uc-docs-files]/[group UUID][uc-docs-groups]/[CDN URL][delivery-docs]/[File Instance][uc-docs-widget-api-file-instance]/[Group Instance][uc-docs-widget-api-group-instance]\nas a value.\n\n```jsx\n\u003cPanel value={[\n  '9dd2f080-cc52-442d-aa06-1d9eec7f40d1',\n  'https://ucarecdn.com/fdfe4e67-f747-4993-91f5-be21d6d3c1a6/',\n  '9ef9af26-7356-4428-b69c-1b920f947989~2'\n]} /\u003e\n```\n\n\u003cbr\u003e\n\n#### `onChange: (fileInstanceList: FileInstance[]) =\u003e void`\n\nSet a function to be called whenever **files state changes**.\n\n* [FileInstance object description][api-refs-file-instance]\n\u003c!-- TODO: * [Example][sandbox-on-change] --\u003e\n\n\u003cbr\u003e\n\n#### `onProgress: (uploadInfoList: UploadInfo[]) =\u003e void`\n\nSet a function to be called whenever **progress state changes**.\n\n* [UploadInfo object description][api-refs-upload-info]\n\u003c!-- TODO: * [Example][sandbox-on-change] --\u003e\n\n\u003cbr\u003e\n\n#### `ref: panelApiRef`\n\nDefine a reference object to address the Dialog API wrapper.\n\n[Dialog API reference][api-refs-dialog]\n\u003c!-- TODO: * [Example][sandbox-ref] --\u003e\n\n```typescript\ninterface DialogApi {\n  addFiles(type: string, files: any[]): void;\n  addFiles(files: Array\u003cJQuery.Deferred\u003cFileInfo\u003e\u003e): void;\n  switchTab(tab: string): void;\n  getFileColl(): CollectionOfPromises\u003cFileInfo\u003e;\n  hideTab(tab: string): void;\n  showTab(tab: string): void;\n  isTabVisible(tab: string): boolean;\n  onTabVisibility(callback: OnTabVisibilityCallback): void;\n}\n```\n\n\u003cbr\u003e\n\n#### Those methods works exactly the same way as in `Widget` component:\n\n* [`onTabChange`](#ontabchange-tabname-string--void)\n* [`customTabs`](#customtabs-key-string-customtabconstructor)\n* [`validators`](#validators-validator)\n* [`preloader`](#preloader-componenttype)\n* [`tabsCss`](#tabscss-string)\n\n#### Those methods aren't supported in `Panel` component:\n\n* [`onFileSelect`](#onfileselect-fileinfo-fileinfo--filesinfo--null--void)\n* [`onDialogOpen`](#ondialogopen-dialog-dialogapi--void)\n* [`onDialogClose`](#ondialogclose-objs-fileinfo--filesinfo--null--void)\n\n\n### Widget configuration\n\njQuery File Uploader can be deeply customized to suit your UX/UI. You can define\nallowed upload sources, implement file validation, and more.\n\nAll the options defined in the [widget options docs][widget-options-docs] are\nalso supported in the component as props (use the **camelCase** notation, you\ncan find it under “Object key” in the referenced article).\n\nUse the live [jQuery File Uploader][uc-widget-configure] as a starting\npoint and consider checking out the docs on [widget configuration][uc-docs-widget-config].\n\n## Security issues\n\nIf you ran into something in Uploadcare libraries that might have security\nimplications, please hit us up at [bugbounty@uploadcare.com][uc-email-bounty] or\nHackerone.\n\nWe’ll contact you shortly to fix and issue prior to any public disclosure.\n\n## Feedback\n\nWe want to hear your issue reports and feature requests at\n[hello@uploadcare.com][uc-email-hello].\n\n\n[es6-debate]: https://gist.github.com/Rich-Harris/51e1bf24e7c093469ef7a0983bad94cb\n[build-img]: https://github.com/uploadcare/react-widget/actions/workflows/checks.yml/badge.svg\n[build-link]: https://github.com/uploadcare/react-widget/actions/workflows/checks.yml\n[npm-img]: https://img.shields.io/npm/v/@uploadcare/react-widget.svg\n[npm-link]: https://www.npmjs.com/package/@uploadcare/react-widget\n[widget-options-docs]: https://uploadcare.com/docs/file_uploads/widget/options/#options?utm_source=github\u0026utm_campaign=react-widget\n[delivery-docs]: https://uploadcare.com/docs/delivery/?utm_source=github\u0026utm_campaign=react-widget\n[react-guide]: https://uploadcare.com/docs/guides/react/?utm_source=github\u0026utm_campaign=react-widget\n[custom-tabs-docs]: https://uploadcare.com/docs/api_reference/javascript/custom_tabs/?utm_source=github\u0026utm_campaign=react-widget\n\n[api-refs-upload-info]: https://uploadcare.com/docs/file-uploader-api/files-uploads/#upload-info\n[api-refs-file-instance]: https://uploadcare.com/docs/file-uploader-api/files-uploads/#file-new-instance\n[api-refs-props]: https://uploadcare.com/docs/api_reference/rest/accessing_files/#properties?utm_source=github\u0026utm_campaign=react-widget\n[api-refs-dialog]: https://uploadcare.com/docs/file_uploader_api/dialog_panel/#dialog-api?utm_source=github\u0026utm_campaign=react-widget\n[api-refs-validation]: https://uploadcare.com/docs/file_uploads/widget/moderation/?utm_source=github\u0026utm_campaign=react-widget\n[multi-type-desc]: https://github.com/uploadcare/react-widget/blob/cbcbb8772052d489c9c1003ca9f91cb857bf1120/types/index.d.ts#L317-L320\n\n[uc-email-bounty]: mailto:bugbounty@uploadcare.com\n[uc-email-hello]: mailto:hello@uploadcare.com\n[uc-widget-configure]: https://uploadcare.com/widget/configure/?utm_source=github\u0026utm_campaign=react-widget\n[uc-feature-widget]: https://uploadcare.com/features/widget/?utm_source=github\u0026utm_campaign=react-widget\n[uc-docs-widget-config]: https://uploadcare.com/docs/uploads/widget/config/?utm_source=github\u0026utm_campaign=react-widget\n[uc-docs-widget-js-api]: https://uploadcare.com/docs/api_reference/javascript/?utm_source=github\u0026utm_campaign=react-widget\n[uc-docs-widget-styling]: https://uploadcare.com/docs/file_uploader_api/tabs_styling/?utm_source=github\u0026utm_campaign=react-widget\n[uc-sign-up]: https://uploadcare.com/accounts/signup/\n[uc-docs-groups]: https://uploadcare.com/docs/delivery/group_api/#groups\n[uc-docs-widget-api-group-instance]: https://uploadcare.com/docs/file-uploader-api/file-groups/#new-instance\n[uc-docs-widget-api-file-instance]: https://uploadcare.com/docs/file-uploader-api/files-uploads/#file-new-instance\n[uc-docs-files]: https://uploadcare.com/docs/concepts/#uploads\n[uc-docs-widget-single-file-value]: https://uploadcare.com/docs/file-uploader-api/widget/#single-file-value\n[uc-docs-widget-open-dialog]: https://uploadcare.com/docs/file-uploader-api/widget/#widget-open-dialog\n[uc-docs-widget-reload-info]: https://uploadcare.com/docs/file-uploader-api/widget/#widget-reload-info\n[uc-docs-metadata]: https://uploadcare.com/docs/file-metadata/\n[uc-docs-image-editor]: https://uploadcare.com/docs/uploads/image-editor/\n\n[sandbox-simple-demo]: https://codesandbox.io/s/uploadcarereact-widget-7xpqp\n[sandbox-props]: https://codesandbox.io/s/uploadcarereact-widget-props-example-oqk0v\n[sandbox-on-change]: https://codesandbox.io/s/uploadcarereact-widget-onchange-example-o376j\n[sandbox-on-file-select]: https://codesandbox.io/s/uploadcarereact-widget-onfileselect-example-4kwyx\n[sandbox-custom-tab]: https://codesandbox.io/s/4xz0k\n[sandbox-validators]: https://codesandbox.io/s/vxnjb\n[sandbox-ref]: https://codesandbox.io/s/keu2y\n[sandbox-gatsby]: https://codesandbox.io/s/23pqs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuploadcare%2Freact-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuploadcare%2Freact-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuploadcare%2Freact-widget/lists"}