CldUploadWidget Configuration

Basic Props

children

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()}>
        Upload
      </button>
    );
  }}
</CldUploadWidget>

Parameters

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.

Example

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

signatureEndpoint

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

signatureEndpoint="/api/sign-cloudinary-params"

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

uploadPreset

uploadPreset="my-upload-preset"

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

Events

Upload Widget events allow you to tap into different points of the upload lifecycle including when an upload has completed, but also when it starts the queue and more. To allow interaction with these events, CldUplodWidget provides both "Callback Functions" and "Actions".

The difference between the Callback Functions and the Actions is the second argument of options that the Callback Functions receive. While Callback Functions pass in both the results along with the widget instance and instance methods, Actions only pass along the results in order to support the Server Actions workflow.

Callback Functions

Actions

To learn more about the event callbacks and when they trigger, see: https://cloudinary.com/documentation/upload_widget_reference#events (opens in a new tab)

Example

<CldUploadWidget
  ...
  onSuccess={(results) => {
    console.log('Public ID', results.info.public_id);
  }}
/>

Callback Parameters

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

Example

<CldUploadWidget
  ...
  onSuccess={(results) => {
    console.log('Public ID', results.info.public_id);
  }}
/>

options

results

The event and results that were returned from the event.

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.

Example

{
  height: 400;
  public_id: 'mypublicid';
  secure_url: 'https://res.cloudinary.com/.../mypublicid';
  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.

Advanced

Configuration

config

Allows configuration for the Cloudinary environment.

Examples

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

options

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.

options={{
  sources: ['local', 'url', 'unsplash'],
  multiple: true,
  maxFiles: 5
}}

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