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="<Upload Preset>">
  {({ open }) => {
    function handleOnClick(e) {
      e.preventDefault();
      open();
    }
    return (
      <button className="button" onClick={handleOnClick}>
        Upload an Image
      </button>
    );
  }}
</CldUploadWidget>

If using the Next.js 13 app directory, you must add the "use client" directive at the top of your file.

URL:

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 }) => {
    function handleOnClick(e) {
      e.preventDefault();
      open();
    }
    return (
      <button className="button" onClick={handleOnClick}>
        Upload an Image
      </button>
    );
  }}
</CldUploadWidget>

If using the Next.js 13 app directory, you must 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.

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

URL:

Learn More about CldUploadWidget

Examples Configuration