Next Cloudinary v6 now available! View Changelog

<CldUploadWidget />

CldUploadWidget Configuration

Basic Props

childrenfunction{(options) => {}}
signatureEndpointstring/api/sign-cloudinary-params.jsMore Info
uploadPresetstringmy-upload-presetMore Info (opens in a new tab)


A function that returns a React component that receives instance methods and options for the widget.

<CldUploadWidget uploadPreset="<Upload Preset>">
  {({ open }) => {
    return (
      <button className="button" onClick={() => open()}>


By passing in a function as the child of the Upload Widget, you're able to gain access to the widget, results, and instance methods to interface directly with the widget.

cloudinaryCloudinaryThe Cloudinary instance which creates and manages the Widget instance.
errorstringThe error, if any, produced by an upload widget action.
isLoadingbooleanDesignates whether the upload widget is loading and initializing.
resultsobjectThe event that triggered the results and information related to that event, which can include upload results.
widgetWidgetThe widget instance attached to the current component.
[Instance Methods]FunctionSee Instance Methods below


  {({ cloudinary, widget, open }) => {
    // Return UI


An API endpoint used to sign the parameters generated during upload.


Learn more about generating signatures (opens in a new tab) on the Cloudinary docs.



Learn more about upload presets (opens in a new tab) on the Cloudinary docs.


Callback Functions

onAbortfunction(results, options) => { }More Info (opens in a new tab)
onBatchCancelledfunction(results, options) => { }More Info (opens in a new tab)
onClosefunction(results, options) => { }More Info (opens in a new tab)
onDisplayChangedfunction(results, options) => { }More Info (opens in a new tab)
onErrorfunction(error, options) => { }
onOpenfunction(widget) => { }
onPublicIdfunction(results, options) => { }More Info (opens in a new tab)
onQueuesEndfunction(results, options) => { }More Info (opens in a new tab)
onQueuesStartfunction(results, options) => { }More Info (opens in a new tab)
onRetryfunction(results, options) => { }More Info (opens in a new tab)
onShowCompletedfunction(results, options) => { }More Info (opens in a new tab)
onSourceChangedfunction(results, options) => { }More Info (opens in a new tab)
onSuccessfunction(results, options) => { }More Info (opens in a new tab)
onTagsfunction(results, options) => { }More Info (opens in a new tab)
onUpload (Deprecated)function(results, widget) => { }
onUploadAddedfunction(results, options) => { }More Info (opens in a new tab)

To learn more about the event callbacks and when they trigger, see: (opens in a new tab)


  onSuccess={(results) => {
    console.log('Public ID',;

Callback Parameters

Most of the callbacks provide a set of options that give access to the results, options, and widget instance.

errorstringIf an error occurs, an explanation of what failed.
optionsobjectInstance methods and the widget instance.
resultsobjectThe event that drove the callback and the info pertaining to the event (such as a resource).

Future releases will work to create a more consistent interface between older methods and more recently added methods.


  onSuccess={(results) => {
    console.log('Public ID',;


widgetWidget InstanceThe Cloudinary Upload Widget instance being rendered.
[Instance Methods]FunctionSee Instance Methods below


The event and results that were returned from the event.

eventstringThe event that triggered the callback.
infostring | objectInformation pertaining to the triggered event, such as the resulting uploaded resource.

A common use of results could be to retrieve an uploaded asset, which would be made available in the info property from the resulting event. If the result is a resource, the shape will include some of the following details.


  height: 400;
  public_id: 'mypublicid';
  secure_url: '';
  width: 400;

Instance Methods

The Upload Widget exposes instance methods that gives the ability to have greater control and flexbility over the upload experience.

They're exposed either through event handler callback or child function parameters.

closefunctionCloses and resets the widget to its initial state without removing it from memory.
destroyfunctionHides a previously rendered widget while retaining its current state in memory.
hidefunctionCloses the widget and completely removes it from the DOM. Returns a promise that resolves upon cleanup completion.
isDestroyedfunctionReturns whether the destroy method was called on this instance.
isMinimizedfunctionReturns whether the widget is currently minimized.
isShowingfunctionReturns whether the widget is currently visible.
minimizefunctionMinimizes the widget.
openfunctionRenders an existing widget currently in memory, but that is not currently displayed.
showfunctionRenders a previously hidden widget.
updatefunctionUpdates a widget currently in memory with new options.



configobject-{ url: { cloudName: 'spacejelly' } }More Info (opens in a new tab)
optionsobject {encryption: {...}}More Info (opens in a new tab)


Allows configuration for the Cloudinary environment.


  cloud: {
    cloudName: '<Your Cloud Name>',
    apiKey: '<Your API Key>'


Parameters used to customize and configure the Upload Widget instance. These options are passed in directly to the Upload Widget, exposing all available parameters through the options object.

  sources: ['local', 'url', 'unsplash'],
  multiple: true,
  maxFiles: 5

Learn more about Upload Widget parameters (opens in a new tab) on the Cloudinary docs.