@uploadcare/react-widget

File Uploader for React

This is a component made to integrate Uploadcare Widget into your React app easily; convenient props management and lazy loading are bundled.

The component allows users to upload files from their devices, social media, cloud storage, and more. All that without any backend code that’s usually required to handle uploads.

Read Uploadcare + React Integration Guide

Note, this library comes untranspiled. It means that if you want to support IE11, make sure you transpile node_modules. Learn more

• Install
• Usage
• Configuration
  • Component configuration
  • Widget configuration
• Security issues
• Feedback

Install

npm i @uploadcare/react-widget

Usage

import { Widget } from "@uploadcare/react-widget";

{/* Also, you can save 30% in bundle size by using English-only version: */}
import { Widget } from "@uploadcare/react-widget/en";

<Widget publicKey="YOUR_PUBLIC_KEY" />;

• Basic usage example on CodeSandbox
• Gatsby basic usage example on CodeSandbox

To use the component, you should have an API key from Uploadcare.

Uploadcare account is free and gives access to serverless file uploads, transformations, CDN delivery, and APIs. After sign up, you land on the Dashboard where you manage projects. Projects are identified by their public keys: replace YOUR_PUBLIC_KEY with your project’s Public API Key and you are all set.

You can refer to our integration guide for more details.

Configuration

Component configuration

value: string

Set a file UUID/group UUID or a CDN URL as a value.

<Widget value='9dd2f080-cc52-442d-aa06-1d9eec7f40d1' />
<Widget value='9dd2f080-cc52-442d-aa06-1d9eec7f40d1~12' />

onChange: (fileInfo: FileInfo) => void

Set a function to be called after a file is uploaded and ready.

• FileInfo object description
• Example

onFileSelect: (fileInfo: FileInfo) => void

Set a function to be called after a new file is selected.

• FileInfo object description
• Example

customTabs: {[string]: CustomTabConstructor}

Add custom tabs for a widget.

function myTab(container, button, dialogApi, settings, name, uploadcare) {
  ...
}

<Widget customTabs={{ tabname: myTab }} />

Note that we added the fifth argument to the custom tab constructor — an uploadcare object. The widget is lazily-loaded, so you don’t have to import uploadcare-widget separately for your custom tab.

Remember that you have to also include your custom tab in the tabs prop to make it work:

<Widget customTabs={{ tabname: myTab }} tabs='tabname' />

• Custom tabs docs
• Example

validators: Validator[]

Set validators for a widget. Validator is a JavaScript function that receives a fileInfo object for each uploaded file and throws an exception if that file does not meet validation requirements.

const fileTypeLimit = (tps) => {
  cosnt types = tps.split(' ')
  return function(fileInfo) {
    if (fileInfo.name === null) {
      return
    }
    const extension = fileInfo.name.split('.').pop()

    if (!types.include(extension)) {
      throw new Error('fileType')
    }
  }
}

const validators = [fileTypeLimit('mp3 avi mp4')];

<Widget validators={validators} />

• Validator object description
• FileInfo object description
• Example

preloader: Component

Set a custom preloader. Preloader is a Component to be shown while a widget is loading.

ref: widgetApiRef

Define a reference object to hold the Widget API wrapper. Use it to access methods: openDialog, reloadInfo, and getInput.

const Example = () => {
 const widgetApi = useRef();
 return (
   <>
     <button onClick={() => widgetApi.current.openDialog()}>
       Click me
     </button>
     <Widget ref={widgetApi} publicKey=“demopublickey” />
   </>
 );
};

• Widget API reference
• Example

Widget configuration

Uploadcare Widget can be deeply customized to suit your UX/UI. You can define allowed upload sources, implement file validation, and more.

All the options defined in the widget options docs are also supported in the component as props (use the camelCase notation, you can find it under “Object key” in the referenced article).

Use the live Uploadcare Widget Configurator as a starting point and consider checking out the docs on widget configuration.

Security issues

If you think you ran into something in Uploadcare libraries which might have security implications, please hit us up at [e-mail] or Hackerone.

We’ll contact you personally in a short time to fix an issue through co-op and prior to any public disclosure.

Feedback

Issues and PRs are welcome. You can provide your feedback or drop us a support request at [e-mail].