The CldUploadWidget creates a new instance of the Cloudinary Upload Widget giving you an easy way to add upload capabilities to your Nuxt app.

Basic Usage

The CldUploadWidget will not render any UI by default. It will instead only render what's returned from the slot (see more below).

There are two options when using the CldUploadWidget: signed and unsigned. These options allow you to control the amount of security and restrictions you place on uploads.

To learn more about signed and unsigned upload, check out the Cloudinary docs.


To give unsigned access for upload, provide an upload preset as part of the component configuration.

Note: The upload preset requires that unsigned uploads are permitted.

Use the following to generate an unsigned upload widget:

<CldUploadWidget v-slot="{ open }" uploadPreset="nuxt-cloudinary-unsigned">
  <button type="button" @click="open">Upload an Image</button>


Signing upload requests requires passing in an endpoint to the component.

You can do this by creating a serverless function that reads the parameters as the body and returns an object with the signature.

Use the following to generate an signed upload widget:

  v-slot="{ open }"
  signatureEndpoint="<API Endpoint (ex: /api/sign-cloudinary-params)>"
  <button type="button" @click="open">Upload an Image</button>

Here's an example of how you could process the signature in an API endpoint that signs a request:

import { v2 as cloudinary } from "cloudinary";

export default eventHandler(async (event) => {
  const signature = cloudinary.utils.api_sign_request(

  return { signature };

To use the above, create a Node-based API route, add the snippet, and use that endpoint as the signatureEndpoint prop.

General Props

Prop NameTypeExample
childrenfunction{ (options) => {} }
optionsobject{ encryption: {...} }

Event Props

Prop NameTypeExample
onErrorfunction(error, widget) => { }
onOpenfunction(widget) => { }
onUploadfunction(result, widget) => { }
onAbortfunction(result, options) => { }
onBatchCancelledfunction(result, options) => { }
onClosefunction(widget) => { }
onDisplayChangedfunction(result, options) => { }
onPublicIdfunction(result, options) => { }
onQueuesEndfunction(result, options) => { }
onQueuesStartfunction(result, options) => { }
onRetryfunction(result, options) => { }
onShowCompletedfunction(result, options) => { }
onSourceChangedfunction(result, options) => { }
onSuccessfunction(result, options) => { }
onTagsfunction(result, options) => { }
onUploadAddedfunction(result, options) => { }

To learn more about the event callbacks and when they trigger, see:

Callback Options

Most of the callbacks provide a set of options that give access to the widget instance and allow more interaction.

widgetWidgetThe widget instance attached to the current component.
Instance MethodsfunctionSee below.