Next.js SDK

The Cloudinary Next.js SDK provides simple, yet comprehensive image and video rendering, transformation, optimization, and delivery capabilities that you can implement using code that integrates seamlessly with your existing Next.js application.

How would you like to learn?

Install

Install the next-cloudinary package using the NPM package manager:

To avoid unexpected changes in production, consider installing a specific version rather than the latest, for example npm install --save-exact next-cloudinary@7.0.0. Without --save-exact, npm saves a version range such as ^7.0.0 in your package.json.

Configure

Set required configuration parameters

Add your Cloudinary cloud name to your environment variables:

Set additional configuration parameters

In addition to the required configuration parameters, you can define a number of optional environment variables if relevant:

Configuration video tutorials

The following tutorials can help you install and set up your SDK:

See more Next.js video tutorials.

Use

Once you've installed and configured the Next.js SDK, you can use it for:

• Rendering and transforming images - Render your images with transformations applied, using the CldImage component. See examples
• Rendering and transforming videos - Render your videos with transformations applied, using the CldVideoPlayer component. See example
• Uploading assets - Use the upload components to easily add upload functionality to your application. See example
• Generating social media cards - Create Open Graph images and social media cards with the CldOgImage component. See example

Quick examples: Image transformations

Here are two quick examples to get you started with image transformations:

• Image transformation example 1 - Apply a sepia effect to an image
• Image transformation example 2 - Apply multiple transformations

A key benefit of the Next.js SDK is that it automatically optimizes images for responsiveness, format and quality. In the examples below, you'll notice c_limit, f_auto and q_auto automatically added to the generated URLs.

• c_limit: Scales the image down to fit within the size you specify, but never scales it up. The Next.js SDK also generates multiple sizes of each image for responsive delivery, as described in the examples below. Learn more
• f_auto: Delivers the image in the best format for the requesting browser. Learn more
• q_auto: Compresses the image enough to reduce its size without impacting visual quality. Learn more

Image transformation example 1

The following Next.js code renders the front_face.jpg image with a sepia effect applied:

The width and height props should match the actual dimensions of the image (here, 292x282 pixels). This code creates the HTML required to render the following transformation URL:

The component actually renders two URLs in a srcset, one for standard screens and one for high-density (2x) screens, so that browsers can pick the size that suits the device:

Image transformation example 2

You can apply more than one transformation at a time to give more interesting results:

This code performs all of the following on the original front_face.jpg image before delivering it:

• Crop to a 150x150 thumbnail using face-detection gravity to automatically determine the location for the crop
• Round the corners with a 20 pixel radius
• Apply a sepia effect
• Overlay the Cloudinary logo on the southeast corner of the image (with a slight offset). Scale the logo overlay down to a 50 pixel width, with increased brightness and partial transparency (opacity = 60%).
• Rotate the resulting image (including the overlay) by 10 degrees

And here's the URL that's automatically generated and rendered from the above code:

Quick example: Video transformations

Here's an example to get you started with video transformations using the CldVideoPlayer component.

The following Next.js code renders the ship.mp4 video with the Cloudinary Video Player and transformations applied:

This code performs the following transformations on the video:

• Crop to a 1:1 aspect ratio (square) with a width of 300 pixels, using automatic gravity to determine the focal point
• Apply a blur effect with strength 50
• Apply maximum rounding to create a circular video

Uploading assets

The Next.js SDK provides two components for uploading assets, CldUploadButton and CldUploadWidget.

CldUploadButton

A drop-in button component that opens the Cloudinary Upload Widget:

CldUploadWidget

A customizable upload widget component:

Social media cards

Generate Open Graph images and social media cards with the CldOgImage component:

The component automatically generates the appropriate meta tags for social media platforms with links to the Cloudinary-hosted images.

Helper methods

In addition to components, the Next.js SDK provides helper methods for generating Cloudinary URLs:

getCldImageUrl

Generate a Cloudinary image URL using the same API as CldImage:

Learn more

getCldOgImageUrl

Generate a Cloudinary URL specifically for OG Images or Social Media Cards:

Learn more

getCldVideoUrl

Generate a Cloudinary video URL:

Learn more

Next.js App Router

The Next.js SDK fully supports the App Router introduced in Next.js 13. In version 7, the Cloudinary components include the 'use client' directive, so you can use them directly in Server Components. If you pass event handlers or a render function to a component, or use hooks or other client-only code in the same file, add 'use client' at the top of that file. In version 6, add 'use client' at the top of every file that uses Cloudinary components. The following example is a Server Component, so it doesn't need the directive in version 7:

Upgrade from version 6 to version 7

Version 7 uses Cloudinary Video Player v4 in CldVideoPlayer, and updates the supported versions of Next.js, React, and Node.js. Many projects can upgrade without code changes, but check the following before you switch:

• Requirements: Your project must use Next.js 16 or later, React 18.2 or 19, and Node.js 22 or later.
• Upload callbacks: The deprecated onUpload callback is removed from CldUploadWidget and CldUploadButton. Use onSuccess instead. Its second argument is now an options object:

• Video player styling: CldVideoPlayer now uses Cloudinary Video Player v4.1.2 (previously v1.11.1). If you customize the player with your own CSS, check that it still applies. If you import next-cloudinary/dist/cld-video-player.css, it updates automatically.
• Package imports: Import only from next-cloudinary and next-cloudinary/dist/cld-video-player.css. Other internal paths, such as next-cloudinary/dist/index.js, no longer resolve.
• TypeScript types: The overlay option is removed (use overlays), assetType accepts only 'image', 'images', 'video', 'videos', or 'all', and the analytics argument of getCldImageUrl and getCldVideoUrl no longer accepts false. If you import option types directly from @cloudinary-util/url-loader, some names and shapes have changed.
• Known limitation: When you set aspectRatio on CldVideoPlayer, the poster image doesn't load, although the video plays normally. As a workaround, also set cropMode="fill", which crops the video to that ratio. cropMode isn't in the TypeScript types yet, so in TypeScript projects pass it with a cast, for example {...({ cropMode: 'fill' } as object)}. A fix is planned for a follow-up release.

By upgrading, you also get:

• Custom posters saved in the Video Player Studio are shown automatically in CldVideoPlayer.
• 'use client' is built into CldImage, CldUploadButton, CldUploadWidget, and CldVideoPlayer, so you can use them directly in App Router Server Components. If you pass event handlers or a render function to a component, use it in a Client Component.
• A seed option for fillBackground.
• More complete TypeScript types, such as hue and noise.
• Fixes for CldVideoPlayer re-initializing after navigating away and back, repeated q_auto in video URLs, and overlay text that contains commas.

Sample projects

Take a look at the Next.js sample projects page to help you get started integrating Cloudinary into your Next.js application.