Website • Docs • Blog • Twitter
Welcome to the Uploadcare React Uploader documentation! This documentation provides guidance on how to use the Uploadcare React Uploader in your projects, along with details about its features, installation process, usage examples, customization options, event handling, and security considerations.
@uploadcare/react-uploader provides React components for file uploads powered by Uploadcare: FileUploaderRegular, FileUploaderMinimal, and FileUploaderInline. It wraps @uploadcare/file-uploader Web Components with full React prop typing, camelCase event handlers (onModalOpen, etc.), apiRef access to the underlying File Uploader API, configRef access to the <uc-config> element, and customizable styles via className and classNameUploader props. For Next.js, import from @uploadcare/react-uploader/next to disable SSR automatically.
- Install the package:
npm install @uploadcare/react-uploader- Connect React Uploader from your script file:
import { FileUploaderRegular } from "@uploadcare/react-uploader";
import "@uploadcare/react-uploader/core.css";
<FileUploaderRegular pubkey="YOUR_PUBLIC_KEY"/>;An easy way to connect React Uploader to your project and utilize the available API props. We provide a full set of props that are used in File Uploader. For review we suggest you to look at the documentation.
For convenience, we provide the ability to access the File Uploader API using apiRef.
You can see what methods are available in apiRef in the documentation.
import React, {useRef, useEffect} from "react";
import {
FileUploaderRegular,
UploadCtxProvider
} from "@uploadcare/react-uploader";
import "@uploadcare/react-uploader/core.css";
const Example = () => {
const uploaderRef = useRef<UploadCtxProvider | null>(null);
<FileUploaderRegular apiRef={uploaderRef} pubkey="YOUR_PUBLIC_KEY"/>;
}configRef gives you the underlying <uc-config> element, the same way apiRef gives you the upload context.
Use it to read the current config or to set an option on the element directly.
import React, {useRef} from "react";
import {FileUploaderRegular, type Config} from "@uploadcare/react-uploader";
import "@uploadcare/react-uploader/core.css";
const Example = () => {
const configRef = useRef<Config | null>(null);
return <FileUploaderRegular configRef={configRef} pubkey="YOUR_PUBLIC_KEY"/>;
}The AI Image Editor plugin adds a Generate image source and an AI Edit action on uploaded images. It needs @uploadcare/file-uploader 1.34 or later, which this package already depends on.
npm install @uploadcare/ai-image-editorPass the plugin in plugins and add ai-image-editor to sourceList. The plugin's own options (useAiEditor and the aiEditor* keys) are props like any other config option:
import {FileUploaderRegular} from "@uploadcare/react-uploader";
import {AiImageEditorPlugin} from "@uploadcare/ai-image-editor/plugin";
import "@uploadcare/react-uploader/core.css";
const plugins = [AiImageEditorPlugin];
const presets = {generate: [{label: "Logo", prompt: "A logo of "}]};
<FileUploaderRegular
pubkey="YOUR_PUBLIC_KEY"
sourceList="local, url, camera, ai-image-editor"
plugins={plugins}
aiEditorPresets={presets}
aiEditorCanvasFit="full"
/>The plugin reads the rest of its settings (public key, CDN, locale, authToken, and so on) from the uploader config, so nothing else needs wiring. See the plugin options for the full list.
Importing the plugin adds its options to the uploader's config types, so they type-check as props. If your project doesn't pick that up, reference the plugin's types once:
/// <reference types="@uploadcare/ai-image-editor/plugin" />AI Image Editor is in public beta and available on paid Uploadcare plans.
Events in React Uploader are the same as in File Uploader, see the documentation. The principle of converting events from blocks to React Uploader:
- All events in React Uploader start with
on. - All events in React Uploader in
camelCase.
import { FileUploaderRegular } from "@uploadcare/react-uploader";
import "@uploadcare/react-uploader/core.css";
<FileUploaderRegular
pubkey="YOUR_PUBLIC_KEY"
onModalOpen={() => {
console.log('modal-open')
}}
/>You can customize the appearance of the React Uploader by using the className prop, which lets you apply custom CSS classes to the FileUploader wrapper, including the Regular, Minimal, and Inline variations.
However, if you need to assign a class specifically to the uploader file. Use the classNameUploader prop.
import { FileUploaderRegular } from "@uploadcare/react-uploader";
import "@uploadcare/react-uploader/core.css";
<FileUploaderRegular
classNameUploader="uc-dark"
className="fileUploaderWrapper"
pubkey="YOUR_PUBLIC_KEY"
/>;.fileUploaderWrapper uc-file-uploader-regular {
}File Uploader does not support Server-side Rendering (SSR), we have a special import for nextjs that already has SSR disabled.
You will need to import with import @uploadcare/react-uploader/next
'use client'
import { FileUploaderRegular } from "@uploadcare/react-uploader/next";
import "@uploadcare/react-uploader/core.css";
function App() {
return <FileUploaderRegular pubkey="YOUR_PUBLIC_KEY" />
};If you think you ran into something in Uploadcare libraries that might have security implications, please hit us up at bugbounty@uploadcare.com or Hackerone.
We'll contact you personally in a short time to fix an issue through co-op and prior to any public disclosure.
Issues and PRs are welcome. You can provide your feedback or drop us a support request at hello@uploadcare.com.