CldUploadWidget Configuration

Configuration

Prop Type Example
children function {(options) => {}}
options object {encryption: {...}} More Info
signatureEndpoint string {`/api/sign-cloudinary-params.js`} More Info
uploadPreset string {`my-upload-preset`} More Info

children

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

'<script>
  import { CldUploadWidget } from 'svelte-cloudinary'
</script>

<CldUploadWidget uploadPreset="<Upload Preset>" let:open>
      <button class="button" on:click={open}>
        Upload
      </button>
</CldUploadWidget>

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 on the Cloudinary docs.

signatureEndpoint

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

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

Learn more about generating signatures on the Cloudinary docs.

uploadPreset

uploadPreset="my-upload-preset"

Learn more about upload presets on the Cloudinary docs.

Events

Prop Type Example
onAbort function (results, options) => { } More Info
onBatchCancelled function (results, options) => { } More Info
onClose function (widget) => { } More Info
onDisplayChanged function (results, options) => { } More Info
onError function (error, widget) => { }
onOpen function (widget) => { }
onPublicId function (results, options) => { } More Info
onQueuesEnd function (results, options) => { } More Info
onQueuesStart function (results, options) => { } More Info
onRetry function (results, options) => { } More Info
onShowCompleted function (results, options) => { } More Info
onSourceChanged function (results, options) => { } More Info
onSuccess function (results, options) => { } More Info
onTags function (results, options) => { } More Info
onUpload function (results, widget) => { } undefined
onUploadAdded function (results, options) => { } More Info

To learn more about the event callbacks and when they trigger, see: https://cloudinary.com/documentation/upload_widget_reference#events

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.

Prop Type Description
error string If an error occurs, an explanation of what failed.
options object Instance methods and the widget instance.
results object The 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.

Example

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

options

Prop Type Description
widget Widget Instance The Cloudinary Upload Widget instance being rendered.
[Instance Methods] Function See Instance Methods below

results

The event and results that were returned from the event.

Prop Type Description
event string The event that triggered the callback.
info string | object Information 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.

Example

{
  height: 400;
  public_id: 'mypublicid';
  secure_url: 'https://res.cloudinary.com/.../mypublicid';
  width: 400;
  ...
}

Child Function 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.

Prop Type Description
cloudinary Cloudinary The Cloudinary instance which creates and manages the Widget instance.
error string The error, if any, produced by an upload widget action.
isLoading boolean Designates whether the upload widget is loading and initializing.
results object The event that triggered the results and information related to that event, which can include upload results.
widget Widget The widget instance attached to the current component.
[Instance Methods] Function See Instance Methods below

Example

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

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.

Prop Type Description
close function Closes and resets the widget to its initial state without removing it from memory.
destroy function Hides a previously rendered widget while retaining its current state in memory.
hide function Closes the widget and completely removes it from the DOM. Returns a promise that resolves upon cleanup completion.
isDestroyed function Returns whether the destroy method was called on this instance.
isMinimized function Returns whether the widget is currently minimized.
isShowing function Returns whether the widget is currently visible.
minimize function Minimizes the widget.
open function Renders an existing widget currently in memory, but that is not currently displayed.
show function Renders a previously hidden widget.
update function Updates a widget currently in memory with new options.
MIT 2023 ©