Next.js image transformations

Overview

The Next.js SDK provides the CldImage component for rendering images with transformations. The component is built on top of the Next.js Image component, providing all the benefits of Next.js image optimization while adding Cloudinary's powerful transformation capabilities.

If you haven't yet installed the Next.js SDK, you might want to jump to the quick start first.

See also: Next.js video transformations

Image transformations with Next.js

Using CldImage

To transform and display an image asset, use the CldImage component with transformation props. For example:

This produces the following HTML:

The HTML displays the front_face image as a 150 x 150 pixel grayscale thumbnail, focusing on the face:

An advantage of the Next.js SDK is that it adds optimization and responsiveness by default. So, even though you'd expect this transformation to result in these URL parameters, c_thumb,g_face,h_150,w_150/e_grayscale, in reality the URL looks like this:

Required props

These are the props required to use CldImage:

Prop	Type	Required	Example	More Info
alt	string	Yes	Dog catching a frisbee	More Info
height	number/string	Yes, unless using Next Image fill	600	More Info
src	string	Yes	my-public-id	A public ID or a full Cloudinary URL.
width	number/string	Yes, unless using Next Image fill	600	More Info

Next Image props

CldImage extends the Next.js Image component, which means all props available on the Image component are also available on CldImage. For more information, see the Next.js Image documentation.

Using fill

Because CldImage extends Next.js Image, it's important to understand the distinction between what "fill" applies to in different contexts:

• The Next.js Image fill prop displays the image using the native <img /> tag and CSS.
• The Cloudinary fill crop mode crops the image file itself while filling the containing space.

To use the Next.js Image fill mode, set fill or fill={true}.

To use the Cloudinary fill crop mode, set crop="fill".

Using getCldImageUrl

You can also generate a Cloudinary URL directly using the getCldImageUrl helper method and display it in a standard img tag:

The getCldImageUrl method returns the transformation URL:

With the full HTML looking like this:

Notice that this time, the width and height are set as requested.

Ensuring transformation order in chained transformations

When specifying multiple transformations in the CldImage component, or getCldImageUrl method, the order at which they're applied to the URL is not guaranteed. This has implications for transformations that rely on the order in which they're applied, such as overlays, underlays, and chained effects.

For example, cropping an image to keep the right side (east) and then applying rounded corners produces a different result than applying rounded corners first and then cropping:

Crop to east first, then apply rounded corners:

Apply rounded corners first, then crop to east:

Notice that in the second example, the left corners are not rounded because the rounding happened before the image was cropped. Also, the rounding on the right corners is less pronounced because the original image is 1870 x 1250px.

To ensure the order of transformations, use raw transformations.

Raw transformations

The rawTransformations parameter allows you to pass transformation strings using transformation URL syntax. This allows you to control the order in which they're applied to the URL.

With CldImage:

With getCldImageUrl:

The resulting URL:

Using Cloudinary URLs as source

You can pass a full Cloudinary URL as the src prop. The URL must include a version number (/v1234/) to be correctly parsed:

Preserving existing transformations

If your Cloudinary URL already has transformations applied, use preserveTransformations to keep them:

Or, with getCldImageUrl:

Common image transformations

The following transformations are available for both CldImage and getCldImageUrl:

Prop/Name	Type	Default	Example	More Info
angle	number	-	45	More Info
aspectRatio	string	-	16:9	More Info
background	string	-	blue, rgb:0000ff	More Info
crop	string | object	limit	fill	More Info
enhance	boolean	-	true	More Info
extract	string | array | object	-	"space jellyfish"	More Info
fillBackground	boolean | object	-	{ gravity: 'east' }	More Info
gravity	string	auto	faces	More Info
loop	boolean | number	-	true	More Info
recolor	array | object	-	['duck', 'blue']	More Info
remove	string | array | object	-	apple	More Info
removeBackground	boolean | string	false	true	More Info
replace	array | object	-	['apple', 'banana']	More Info
replaceBackground	boolean | string | object	-	true	More Info
restore	boolean	-	true	More Info
zoom	string	-	0.5	More Info
zoompan	boolean | string | object	-	true	More Info

angle

Rotates the image by a specified angle.

Learn more

aspectRatio

Resizes the image to a new aspect ratio.

Usage constraints

The aspectRatio prop works only with specific crop modes: auto, crop, fill, lfill, fill_pad, and thumb.

Because Next.js Image components require width and height props (unless using fill), and these props conflict with aspect ratio transformations, you must use the fill prop when applying aspectRatio.

Requirements for using aspectRatio:

• Set fill={true} on the component
• Use a supported crop mode
• Omit the width and height props

If using getCldImageUrl, you can specify width or height together with aspectRatio:

Learn more

background

Applies a solid color background to transparent or empty areas. You can use color names or RGB values:

Color name:

RGB value:

Learn more

crop

Changes the size of the delivered asset according to the requested width and height dimensions.

The crop prop can be a string (any valid Cloudinary crop mode), or an object (or array of objects) with the following options:

Prop	Type	Example
aspectRatio	string	16:9
gravity	string	See Gravity
height	string	See Height
source	boolean	true
type (crop mode)	string	fill
width	string	See Width
x	number | string	100
y	number | string	200
zoom	string	See Zoom

Dynamic crop modes

When using a dynamic crop mode like thumb, the resulting image may look visually different based on the given dimensions. For instance, an image cropped using thumb with dimensions 600x600 will give different results than 1200x1200 (assuming a gravity of auto or similar, which is the default for CldImage).

This is especially important for responsive images, where the resize mechanism may cause different device sizes to show different-looking images, which doesn't provide a great experience.

To resolve this, when using dynamic crop modes, you can opt into a two-stage crop: first cropping the original source image, then allowing the resize mechanism to handle resizing to the appropriate device size.

Examples

Cropping an image and filling the containing space:

Using a crop of thumb on the original source image:

Using coordinates to crop to a specific location:

Learn more

enhance

Uses AI to enhance the visual appeal of an image:

Learn more

extract

Extracts an area or multiple areas of an image, described in natural language, keeping the content of the extracted area (like background removal) or making the extracted area transparent while keeping the rest of the image, which can be helpful for creating a mask.

The extract prop can be a string, an array of strings, or an object with the following options:

Prop	Type	Example
invert	boolean	true
mode	string	mask
multiple	boolean	true
prompt	string	the woman on the left

Examples

Extracting part of the image by prompt:

Using an array of strings:

Using object syntax:

Using object syntax with multiple prompts:

Learn more

fillBackground

Automatically fills the padded area using generative AI to extend the image seamlessly.

The fillBackground prop can be a boolean (which uses safe defaults), or an object with the following options:

Prop	Type	Example
crop	string	clpad
gravity	string	south
prompt	string	cupcakes

Examples

Applying Generative Fill with defaults:

Customizing options:

Learn more

gravity

The gravity prop determines which part of the image to focus on when cropping:

Common gravity values include: auto, face, faces, center, north, south, east, west, north_east, north_west, south_east, south_west.

Learn more

loop

Loops an animated image infinitely or for the specified number of times.

Learn more

recolor

Uses generative AI to recolor parts of your image, maintaining the relative shading.

The recolor prop can be an array with the objects to be replaced, or an object with the following options:

Prop	Type	Example
multiple	boolean	true
prompt	string | array	duck or ['duck', 'horse']
to	string	blue

Examples

Recoloring an object with an array:

Using the object format:

Learn more

remove

Uses generative AI to remove unwanted parts of your image, replacing the area with realistic pixels.

The remove prop can be a string, an array, or an object with the following options:

Prop	Type	Example
multiple	boolean	true
prompt	string | array	duck or ['duck', 'horse']
removeShadow	boolean	true
region	array	[300, 200, 1900, 3500]

Examples

Removing an object by string:

Removing multiple objects by array:

Removing multiple instances of an object and their shadow:

Removing a region:

Removing multiple regions:

Learn more

removeBackground

Remove the background of an image using AI:

Learn more

replace

Uses generative AI to replace parts of your image with something else.

The replace prop can be an array with the objects to be replaced, or an object with the following options:

Prop	Type	Example
from	string	apple
to	string	banana
preserveGeometry	boolean	true

Examples

Replacing an object using an array:

Using the object format:

Learn more

replaceBackground

Uses generative AI to replace the background of your image.

The replaceBackground prop can be a boolean, string, or object with the following options:

Prop	Type	Example
prompt	string	fish tank
seed	number	2

Examples

Replacing the background based on the image context:

Using a string prompt:

Using the object format:

Learn more

restore

Uses generative AI to restore details in poor quality images or images that may have become degraded through repeated processing and compression.

Learn more

zoom

Controls how close to crop to the detected coordinates when using face-detection, custom-coordinate, or object-specific gravity.

Learn more

zoompan

Also known as the Ken Burns effect, this transformation applies zooming and/or panning to an image, resulting in a video or animated GIF.

zoompan can be applied with safe defaults as a boolean, a string, or an object for advanced customization.

As a string, you can pass in "loop" to automatically loop, or you can pass in raw configuration using the Cloudinary Transformation syntax.

As an object, you can use advanced configuration with the following options:

Prop	Type	Example
loop	boolean | number	true
options	boolean | string	mode_ztr;maxzoom_6.5;du_10

Examples

With defaults:

Add looping:

Customize options (zoom to right, maximum zoom of 6.5, and duration of 10 seconds):

Learn more

Effects and filters

Cloudinary supports a wide variety of effects and artistic filters that help to easily change the appearance of an image.

Prop	Type	Default	Example	More Info
art	string	-	al_dente	More Info
autoBrightness	boolean | string	-	true, 80	More Info
autoColor	boolean | string	-	true, 80	More Info
autoContrast	boolean | string	-	true, 80	More Info
assistColorblind	boolean | string	-	true, 20, xray	More Info
blackwhite	boolean | string	-	true, 40	More Info
blur	boolean | string	-	true, 800	More Info
blurFaces	boolean | string	-	true, 800	More Info
blurRegion	boolean | string	-	true, 1000,h_425,w_550,x_600,y_400	More Info
border	string	-	5px_solid_purple
brightness	boolean | string	-	true, 100	More Info
brightnessHSB	boolean | string	-	true, 100	More Info
cartoonify	boolean | string	-	true, 70:80	More Info
color	string	-	blue
colorize	string	-	35,co_darkviolet	More Info
contrast	boolean | string	-	true, 100, level_-70	More Info
distort	string	-	150:340:1500:10:1500:1550:50:1000, arc:180.0	More Info
fillLight	boolean | string	-	true, 70:20	More Info
gamma	boolean | string	-	true, 100	More Info
gradientFade	boolean | string	-	true, symmetric:10,x_0.2,y_0.4	More Info
grayscale	bool	-	true	More Info
improve	boolean | string	-	true, 50, indoor	More Info
multiply	bool	-	true	More Info
negate	bool	-	true	More Info
oilPaint	boolean | string	-	true, 40	More Info
opacity	number/string	-	40	More Info
outline	boolean | string	-	true, 40, outer:15:200	More Info
overlay	bool	-	true	More Info
pixelate	boolean | string	-	true, 20	More Info
pixelateFaces	boolean | string	-	true, 20	More Info
pixelateRegion	boolean | string	-	true, 35,h_425,w_550,x_600,y_400	More Info
redeye	boolean | string	-	true	More Info
replaceColor	string	-	saddlebrown, 2F4F4F:20, silver:55:89b8ed	More Info
sanitize	bool	true if .svg	true - Only applies to .svg	More Info
saturation	boolean | string	-	true, 70	More Info
screen	bool	-	true	More Info
sepia	boolean | string	-	true, 50	More Info
shadow	boolean | string	-	true, 50,x_-15,y_15	More Info
sharpen	boolean | string	-	true, 100	More Info
shear	string	-	20.0:0.0	More Info
simulateColorblind	boolean | string	-	deuteranopia	More Info
tint	boolean | string	-	true, 100:red:blue:yellow	More Info
trim	boolean | string	-	true, 50:yellow	More Info
unsharpMask	boolean | string	-	true, 500	More Info
vectorize	boolean | string	-	true, 3:0.5	More Info
vibrance	boolean | string	-	true, 70	More Info
vignette	boolean | string	-	true, 30	More Info

Apply various effects to your images using the effects array or individual effect props.

Common effects

blackwhite:

sepia:

grayscale:

blur:

pixelate:

tint:

opacity:

sharpen:

Multiple effects

You can apply multiple effects to an image, either as individual props, or using the effects prop to specify an array of objects.

Example with multiple effects as props:

Example with multiple effects in the effects prop:

Overlays and underlays

Cloudinary gives you the ability to add layers above or below your base asset using overlays and underlays.

You can use these props in the CldImage component:

Prop	Type	Example
overlays	object array	Customizing Overlays & Underlays
text	string	Next Cloudinary
underlay	string	my-public-id
underlays	object array	Customizing Overlays & Underlays

Customizing overlays and underlays

You can customize overlays and underlays using the following properties:

Prop	Type	Example
appliedEffects	array	appliedEffects
effects	array	effects
position	object	position
publicId	string	my-public-id
text	object|string	Next Cloudinary or see text below
url	string	https://.../image.jpg

You can specify the asset to use for the overlay or underlay as a public ID, or a URL of an external image.

appliedEffects

In the appliedEffects array, you can specify blend modes, such as multiply, overlay, and screen, in addition to mask. These are all qualifiers that determine how the layer is applied to the image. In the URL syntax, they are in the same component as the fl_layer_apply flag.

Apply the multiply blend mode to an overlay (the overlay is darker where the base image is darker):

effects

In the effects array, you can specify the transformations to apply to the layer (see Common image transformations and Effects and filters). In the URL syntax, they are in the component(s) before the component containing the fl_layer_apply flag.

Add an overlay, resized to a width of 800 px and colored white:

position

Use the position property to specify where you want the layer to appear, on or under the base image.

The position property can include:

Prop	Type	Example	More Info
angle	number	45	More Info
gravity	string	north_west	More Info
x	number	10	More Info
y	number	10	More Info

Add an overlay to the top right of the base image, offset by 50 pixels, at an angle of 20 degrees:

text

You can overlay text on an image, either by providing the text in the text property and using default styling, or by using the text object to customize text overlaid on your image.

The text object can include:

Prop	Type	Example	More Info
border	string	20px_solid_blue	More Info
color	string	blueviolet	More Info
fontFamily	string	Open Sans	More Info
fontSize	number	48	More Info
fontWeight	string	bold	More Info
letterSpacing	number	14	More Info
lineSpacing	number	14	More Info
stroke	bool	true in coordination with Border	More Info
textDecoration	string	underline	More Info

Add text with default styling to an image:

Add customized text to an image:

Apply effects to text overlays:

Image underlays

If you're placing an image behind another image, with no transformations, you can set the underlay prop to the public ID of the image.

Place the cld-sample-2 image behind the cld-sample-3 image:

To apply transformations to an underlay image, or if you want to add multiple underlays, you can use the underlays prop.

Use multiple images as underlays:

Configuration and delivery options

Configure how your assets are delivered and accessed:

Prop	Type	Default	Example	More Info
assetType	string	image	video	More Info
config	object	-	{ url: { secureDistribution: 'spacejelly.dev' } }	More Info
deliveryType	string	upload	fetch	More Info
defaultImage	string	-	myimage.jpg	More Info
flags	array	-	['keep_iptc']	More Info
seoSuffix	string	-	my-image-content	More Info
version	number	-	1234	More Info

assetType

Specify the type of asset to be delivered. This is useful for creating image thumbnails from videos:

config

Configure the Cloudinary environment:

deliveryType

Control the delivery type of the image:

defaultImage

Specify a fallback image if the requested image is not available:

flags

Alter the behavior of transformations or delivery:

seoSuffix

Add a descriptive suffix to the URL for better SEO:

version

Specify a version number for the asset:

Event handlers and refs

Handle image loading events and access the underlying DOM element:

Prop	Type	Example	More Info
onError	function/bool	(event) => {}	More Info
onLoad	function	(event) => {}	More Info
ref	ref	Ref	More Info

onError event

Callback that fires when an image fails to load:

onLoad event

Callback that fires when an image loads completely:

Using refs

Pass a ref to access the underlying image element:

Advanced transformations

Chained transformations

You can apply multiple transformation steps by using the effects array or by combining multiple transformation props:

Named transformations

Use pre-defined named transformations from your Cloudinary account:

Strict transformations

Strict transformations give you control over which transformations can be used from your Cloudinary account. When enabled, only named transformations are allowed:

Optimization

The CldImage component and the GetCldImageUrl method automatically apply optimization best practices:

• Automatic format selection (f_auto) - Delivers images in the optimal format for each browser
• Automatic quality (q_auto) - Applies intelligent compression to minimize file size while maintaining visual quality

The auto optimizations are applied by default, but if you prefer, you can specify a certain format and quality to deliver the image:

Disabling optimization

To deliver the image without automatic optimizations, use the unoptimized prop:

Device pixel ratio (DPR)

Set the device pixel ratio for sharper images on high-density displays:

Learn more

Image placeholders

CldImage wraps the Next.js Image component, giving you access to the placeholder API which can display an SVG image while the image itself is loading.

This helps provide a better user experience by showing something meaningful rather than an empty space while the image loads.

You have several options for placeholders:

• placeholder="blur" coupled with a blurDataURL
• placeholder="..." with the contents being a data URL

Blurred image placeholders

To achieve a blurred image effect, convert your Cloudinary image to a Data URL then pass it to your CldImage component.

In a server component, generate the Data URL:

Then use it with CldImage:

Shimmer effect placeholder

Create a shimmer loading effect.

Create the shimmer helper functions:

Use with CldImage:

Responsive images

Responsive images are critical for page performance. CldImage makes them easy by leveraging Next.js's built-in responsive image capabilities combined with Cloudinary's transformation technology.

The component takes advantage of the Next.js Image component, which allows you to specify the sizes you need and handles generating the appropriate image variants automatically.

Using the sizes prop

Use the sizes prop to control how the image responds to different viewport sizes:

This would give you roughly full width images on mobile, a 2-column layout on tablets, and a 3-column layout on desktop views.

How CldImage generates responsive images

CldImage utilizes Cloudinary technology to provide responsive sizing. When you use the sizes prop, the component generates a srcset with multiple image URLs, each optimized for different screen sizes.

For example, the output HTML might look like:

Each image is automatically generated on-the-fly by Cloudinary using the w_<width> URL parameter.

Upscaling behavior

By default, CldImage uses the limit crop mode which prevents Cloudinary from upscaling an image if the requested size is greater than the original. Instead, the browser resizes the image.

To allow Cloudinary to upscale images (which may result in blurry images for sizes larger than the original), set the crop mode to scale:

Responsive images with cropping and resizing

You can combine responsive images with Cloudinary's dynamic cropping and resizing modes. When you specify a crop mode, each responsive size will be cropped accordingly:

Each image will be cropped to a 1:1 ratio. As the Next.js Image component generates an image for each responsive size, Cloudinary uses those sizes when building the URL:

Remote images

Use Cloudinary's transformation and delivery features with images not stored in your Cloudinary account.

Fetching remote images on-the-fly

Use the fetch delivery type to transform remote images without storing them in your Media Library:

Cloudinary will fetch the image, apply transformations, cache it on the CDN, and deliver it.

Auto-uploading remote images

Automatically upload remote images to your Cloudinary Media Library on first request. First, configure auto-upload mapping in your Cloudinary settings:

1. Go to Settings > Upload
2. Find Auto upload mapping
3. Create a mapping:
   • Target Folder: Virtual folder name (e.g., s3-images)
   • Source URL prefix: Base URL of remote storage (e.g., https://my-bucket.s3.amazonaws.com/images/)

Then reference the mapped folder in your src:

Social media cards with CldOgImage

The CldOgImage component allows you to easily generate Open Graph images (social media cards) using the same transformation API as CldImage. This component automatically generates the appropriate meta tags for social media platforms.

Basic usage

The basic required prop is src:

The resulting HTML will include all applicable Open Graph tags:

Transformations for social cards

You can use the same transformation API as CldImage to customize your social media cards:

This example:

• Applies a blue tint to the image
• Removes the background
• Reduces opacity to 40%
• Adds white text overlay with custom font
• Places a background image underneath
• Sets specific alt text and Twitter title

Image size for social cards

By default, the image canvas is based on 2400x1254 pixels, but resized down to 1200x627 pixels. This means you can design the image as if it were 2400x1254, but the resulting image will be optimized to 1200x627 to meet social media platform requirements.

The 1200x627 size satisfies:

• The 1.91:1 ratio requirement
• Minimum size requirements for LinkedIn and other platforms

You can customize the canvas and final size:

Text overlays on social cards

Add custom text to create engaging social media cards:

Background removal for social cards

Create professional social cards by removing backgrounds and adding custom underlays:

Twitter-specific configuration

Customize the Twitter card title:

Excluding specific meta tags

If you need to manage certain meta tags yourself, you can exclude them:

Custom meta tag keys

Customize the keys used for meta tags to avoid duplication:

Using getCldOgImageUrl helper

The getCldOgImageUrl helper function generates Social Card image URLs (Open Graph Images) for use with Next.js App Router metadata. This is particularly useful when you need more control over your metadata configuration or when working with the generateMetadata function.

Basic usage with App Router metadata

The only required parameter is src:

The function returns a URL for the image public ID with default configurations including standard width and height optimized for social media platforms.

Image size and format

By default, the image canvas is based on 2400x1254 pixels but resized down to 1200x627 pixels. This approach:

• Maintains a consistent canvas size when designing elements like overlays
• Ensures the final image meets the 1.91:1 ratio requirement
• Satisfies minimum size requirements for LinkedIn and other platforms
• Keeps file sizes manageable

You can customize the canvas and final size:

The default format is JPG, which provides the best compatibility across social media platforms. While Cloudinary's f_auto parameter works well for websites, JPG is safer for social cards because:

• WebP doesn't have broad support across all social platforms
• JPG reduces initial encoding time, which is critical for social networks to recognize and load images on first share

Platform-specific formats

If you need to optimize for specific platforms, you can generate multiple URLs with different formats:

Transformations with getCldOgImageUrl

Apply the same transformations available in getCldImageUrl:

Background removal example

Create professional social cards with background removal and custom underlays:

Default configuration

getCldOgImageUrl is a derivative of getCldImageUrl with these default settings optimized for Open Graph images:

Property	Default Value	Description
crop	fill	Ensures the image fills the entire canvas
gravity	center	Centers the focal point of the image
width	2400	Canvas width in pixels
height	1254	Canvas height in pixels
widthResize	1200	Final output width after resizing
format	jpg	Output format for maximum compatibility

All other configuration options from getCldImageUrl are available, including transformations, effects, overlays, and more.