Next.js image and video upload

The Next.js SDK provides React components that make it easy to add file upload functionality to your Next.js application. These components wrap the Cloudinary Upload Widget, giving you a ready-made, responsive UI that supports uploads from multiple sources including local files, camera, URL, and more.

You can implement uploads using either unsigned upload presets for quick setup, or signed uploads with server-side signature generation for enhanced security.

Upload options

The Next.js SDK offers two components for uploading assets. Both components open the Cloudinary Upload Widget, a ready-made, responsive user interface that enables your users to upload files from a variety of sources (local files, camera, URL, and more).

• CldUploadButton - A simple button component that opens the upload widget when clicked. Best for straightforward upload functionality.
• CldUploadWidget - A flexible component that provides full programmatic control over the upload widget, including the ability to open it from custom UI elements.

Both components provide access to callback functions, configuration options, and instance methods to customize the upload experience for your users.

Using CldUploadButton

The CldUploadButton component provides the simplest way to add upload functionality to your Next.js app. It renders a button that, when clicked, opens the Cloudinary Upload Widget.

Basic usage

This example shows the minimal setup required to add an upload button to your Next.js application. The uploadPreset prop specifies which upload preset to use, which defines the upload configuration:

Handling upload results

Use the onSuccess callback to handle successful uploads:

Customizing the button

The CldUploadButton component inherits all props from CldUploadWidget (including callback functions like onSuccess, onQueuesEnd, etc.), however, it handles children differently.

Button-specific props:

• className - CSS class name for styling
• onClick - Click event handler function

All other HTML button props (like style, disabled, type, etc.) are spread onto the <button> element, giving you full control over the button's appearance and behavior.

Button content:

You can customize the content inside the button by placing elements between the opening and closing <CldUploadButton> tags. If no content is provided, the button displays "Upload" by default.

Example with custom styling:

Create styling for your button in CSS, for example, in globals.css:

Set the className prop to the name of the class, in this case, custom-button:

This renders a styled button with the text "Upload Files":

Upload Files

Example with default label:

If you don't provide content between the tags, the button displays "Upload":

This renders a styled button with the text "Upload":

Upload

Example with onClick handler:

You can add custom logic when the button is clicked, before the upload widget opens:

Using CldUploadWidget

The CldUploadWidget component provides more control over the upload experience, allowing you to customize when and how the widget opens.

Basic usage

Render function parameters

The render function receives an object with the following parameters:

Example accessing multiple parameters:

Handling upload events

The widget provides callback functions for different events in the upload lifecycle. There are two types of callbacks:

1. Callback Functions - Receive both results and options (including widget instance and instance methods)
2. Action Callbacks - Receive only results (designed for Server Actions workflow)

Callback Functions

These callbacks receive (results, options) or (error, options) parameters:

Example:

This example demonstrates using multiple callback functions to handle different stages of the upload process. It uses onSuccess to capture upload results, onQueuesEnd to automatically close the widget after all uploads complete, and onError to handle any upload failures:

Action Callbacks

These callbacks receive only the (results) parameter for use with Server Actions:

Callback parameters

Most callbacks provide parameters with the following structure:

For Callback Functions:

• results (object) - Contains event (string) and info (object with upload details like public_id, secure_url, width, height, etc.)
• options (object) - Contains widget (Widget instance) and instance methods

For Action Callbacks:

• results (object) - Contains event and info only

Example results object:

Instance methods

The Upload Widget exposes instance methods that provide greater control over the upload experience. These are available through the children function parameters or callback options:

Example using instance methods:

This example demonstrates how to programmatically control the upload widget using instance methods. It creates multiple buttons that allow you to open, close, hide, show, and minimize the widget, as well as check its current state:

Signed vs unsigned uploads

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

Unsigned uploads:

• Simpler to implement (no server-side code required)
• Require an unsigned upload preset
• Anyone with the preset name can upload
• Best for: Public assets, demos, prototypes

Signed uploads:

• More secure (requires server-side signature generation)
• Prevents unauthorized uploads
• Allows more control over upload parameters
• Best for: Production applications, restricted uploads, sensitive content

Using unsigned uploads

Unsigned uploads are the simplest option and work well for public assets. All the examples in Using CldUploadButton and Using CldUploadWidget show unsigned uploads.

For unsigned uploads, you need to set the uploadPreset prop to your unsigned upload preset.

For CldUploadButton:

For CldUploadWidget:

Using signed uploads

Signed upload requests provide enhanced security for your file uploads. This helps prevent unauthorized uploads to your Cloudinary account.

For signed uploads, you need to set the signatureEndpoint prop to an API endpoint that'll provide the signature.

For CldUploadButton:

For CldUploadWidget:

You can optionally also provide a signed upload preset in the uploadPreset prop, but this isn't required for signed uploads.

For CldUploadButton:

For CldUploadWidget:

Creating the signature endpoint

When working in Next.js, you can use the Cloudinary Node SDK in a server-side API route to sign your upload requests.

Step 1: Install the Cloudinary Node SDK

Step 2: Set up environment variables

Add your Cloudinary API credentials to your environment variables:

Step 3: Create the API endpoint

The implementation differs based on whether you're using the App Router or Pages Router.

For App Router (Next.js 13+):

Create a new file at app/api/sign-cloudinary-params/route.js:

For Pages Router:

Create a new file at pages/api/sign-cloudinary-params.js:

That's it! The upload components will now automatically call your signature endpoint before each upload to generate a secure signature.

Configuration

Both CldUploadButton and CldUploadWidget support configuration through props.

Cloudinary environment configuration

The upload components automatically use environment variables for Cloudinary configuration:

• NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME - Your Cloudinary cloud name (required)
• NEXT_PUBLIC_CLOUDINARY_API_KEY - Your API key (optional, for signed uploads)
• CLOUDINARY_API_SECRET - Your API key (optional, for signed uploads)

You can also use the config prop to configure Cloudinary settings:

Upload Widget configuration options

You can pass any Upload Widget configuration option using the options prop:

Common configuration options include:

Example with multiple configuration options: