Getting Started with CldUploadWidget

The CldUploadWidget creates a new instance of the Cloudinary Upload Widget (opens in a new tab) giving you an easy way to add upload capabilities to your Next.js app.

Basic Usage

The CldUploadWidget will not render any UI by default. It will instead only render what's returned from the child function (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 (opens in a new tab).

Unsigned

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:

import { CldUploadWidget } from 'next-cloudinary';
 
<CldUploadWidget uploadPreset="<Your Upload Preset>">
  {({ open }) => {
    return (
      <button onClick={() => open()}>
        Upload an Image
      </button>
    );
  }}
</CldUploadWidget>

Using the App Router in Next.js 13+? Add the "use client" directive at the top of your file.

Signed

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:

import { CldUploadWidget } from 'next-cloudinary';
 
<CldUploadWidget signatureEndpoint="<API Endpoint (ex: /api/sign-cloudinary-params)>">
  {({ open }) => {
    return (
      <button onClick={() => open()}>
        Upload an Image
      </button>
    );
  }}
</CldUploadWidget>

Using the App Router in Next.js 13+? Add the "use client" directive at the top of your file.

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';
// const cloudinary = require('cloudinary').v2;
 
const signature = cloudinary.utils.api_sign_request(body.paramsToSign, process.env.CLOUDINARY_API_SECRET);
 
res.status(200).json({
  signature,
});

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

Learn more about signing uploads.

Or see a full example of an API endpoint used with the Next Cloudinary docs in the Pages Router: https://github.com/colbyfayock/next-cloudinary/blob/main/docs/pages/api/sign-cloudinary-params.js (opens in a new tab)

Composing Widget UI

CldUploadWidget uses Function as a Child component to pass options to the widget UI.

To make this work, use a function as the direct child of a CldUploadWidget Instance:

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

The first and only argument is an object that contains instances of cloudinary, the widget, various instance methods that can control the widget, and other data.

Learn More about CldUploadWidget

Examples Configuration