Next Cloudinary v6 now available! View Changelog

getCldImageUrl
Configuration

getCldImageUrl Configuration

Configuration for getCldImageUrl is the same as CldImage, which both use the same underlying API @cloudinary-util/url-loader (opens in a new tab).

The function takes two main arguments: options and config.

NameTypeExample
optionsobject{ src: 'myimage', ... }
configobject{ cloud: { cloudName: 'name' } }More Info (opens in a new tab)

The function also accepts a third argument of analytics that's intended to be used configure analytics properties for usage statistics.

Basic Options

The basic options available to use with getCldImageUrl include:

NameTypeRequiredExample
heightnumber/stringYes, unless using Next Image fill (opens in a new tab)600More Info (opens in a new tab)
srcstringYesmy-public-id
widthnumber/stringYes, unless using Next Image fill (opens in a new tab)600More Info (opens in a new tab)

Basic Transformations

The getCldImageUrl helper exposes many of Cloudinary's transformations in an easy-to-use way right inside of Next.js.

NameTypeDefaultExample
backgroundstring-blue, rgb:0000ffMore Info (opens in a new tab)
cropstring | objectlimitfillMore Info (opens in a new tab)
fillBackground (Beta)boolean | object-{{ gravity: 'east' }}More Info (opens in a new tab)
gravitystringautofacesMore Info (opens in a new tab)
recolorarray | object-['duck', 'blue']More Info (opens in a new tab)
removestring | array | object-appleMore Info (opens in a new tab)
removeBackgroundboolean | stringfalsetrueMore Info (opens in a new tab)
replacearray | object-['apple', 'banana']More Info (opens in a new tab)
restoreboolean-trueMore Info (opens in a new tab)
zoomstring-0.5More Info (opens in a new tab)
zoompanboolean | string | object-trueMore Info (opens in a new tab)

background

Applies a background to empty or transparent areas.

Examples

background: 'blue'

Learn more about the background transformation (opens in a new tab) on the Cloudinary docs.

crop

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

The crop prop can either be a string, which can accept any valid Cloudinary crop mode (opens in a new tab), or it can accept an object or an array of objects which can take the following options:

NameTypeExample
aspectRatiostring16:9
gravitystringSee Gravity
heightstringSee Height
sourcebooleantrue
type (crop mode)stringfill
widthstringSee Width
zoomstringSee Zoom

Dynamic Crop Modes

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

This is especially important in the context of Responsive Images where due to the resize mechanism, different device sizes may result in different looking images, which doesn't provide a great experience.

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

Versions 5 and below of Next Cloudinary automatically opted getCldImageUrl in to a two-stage cropping to help improve the experience, but it came with drawbacks including prematurely limiting the potential resulting size of an image. Learn more (opens in a new tab).

Examples

Cropping an image and filling the containing space:

crop: 'fill'

Using a crop of thumb on the original source image:

crop: {
  width: 1200,
  height: 1200,
  type: 'thumb',
  source: true
}

Learn more about the crop transformation (opens in a new tab) on the Cloudinary docs.

fillBackground

Generative Fill is currently in beta.

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

The fillBackground prop can either be a boolean, which will use a set of safe defaults to produce a background, or an object, which can take the following options:

NameTypeExample
cropstringclpad
gravitystringsouth
promptstringcupcakes

Examples

Applying Generative Fill with defaults:

fillBackground: true

Customizing options:

fillBackground: {
  crop: 'clpad',
  gravity: 'south',
  prompt: 'cupcakes'
}

Learn more about the Generative Fill transformation (opens in a new tab) on the Cloudinary docs.

gravity

Determines which part of an asset to focus on, and thus which part of the asset to keep, when any part of the asset is cropped

Examples

gravity: 'face'

Learn more about gravity (opens in a new tab) on the Cloudinary docs.

recolor

Generative Recolor is currently in beta.

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

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

NameTypeExample
multiplebooleantrue
promptstring | arrayduck or ['duck', 'horse']
tostringblue

Examples

Recoloring an object with an array:

recolor: ['duck', 'blue']

Or using the object format:

recolor: {
  prompt: 'duck',
  to: 'blue',
  multiple; true
}

Learn more about the Generative Recolor transformation (opens in a new tab) on the Cloudinary docs.

remove

Generative Remove is currently in beta.

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

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

NameTypeExample
multiplebooleantrue
promptstring | arrayduck or ['duck', 'horse']
removeShadowbooleantrue
regionarray[300, 200, 1900, 3500]

Examples

Removing an object by string:

remove: 'apple'

Removing multiple objects by array:

remove: ['apple', 'banana', 'orange']

Removing multiple instances of an object and their shadow with object configuration:

remove: {
  prompt: 'apple',
  multiple: true,
  removeShadow: true
}

Removing a region:

remove: {
  region: [300, 200, 1900, 3500]
}

Removing multiple regions:

remove: {
  region: [
    [300, 200, 1900, 3500],
    [123, 321, 750, 500]
  ]
}

Learn more about the Generative Remove transformation (opens in a new tab) on the Cloudinary docs.

removeBackground

Uses the Cloudinary AI Background Removal add-on (opens in a new tab) to make the background of an image transparent.

The Cloudinary AI Background Removal add-on is required to use this feature.

Examples

removeBackground: true

Learn more about background removal transformation (opens in a new tab) on the Cloudinary docs.

replace

Generative Replace is currently in beta.

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

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

NameTypeExample
fromstringapple
tostringbanana
preserveGeometrybooleantrue

Examples

Replacing an object with an array:

replace: ['apple', 'banana']

Or using the object format:

replace: {
  from: 'apple',
  to: 'banana',
  preserveGeometry; true
}

Learn more about the Generative Replace transformation (opens in a new tab) on the Cloudinary docs.

restore

Generative Restore is currently in beta.

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

The restore prop can be used as a boolean.

Examples

restore: true

Learn more about the Generative Restore transformation (opens in a new tab) on the Cloudinary docs.

zoom

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

Examples

zoom: '0.75'

Learn more about the zoom transformation (opens in a new tab) on the Cloudinary docs.

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:

NameTypeExample
loopboolean | stringtrue
optionsboolean | stringmode_ztr;maxzoom_6.5;du_10

Examples

With defaults:

zoompan: true

Add looping:

zoompan: 'loop'

Customize options:

zoompan: {
  loop: 'loop:2', // Will loop twice
  options: 'mode_ztr;maxzoom_6.5;du_10'
}

Learn more about the zoompan transformation (opens in a new tab) on the Cloudinary docs.

Filters & Effects

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

NameTypeDefaultExample
artstring-al_denteMore Info (opens in a new tab)
autoBrightnessboolean | string-true, 80More Info (opens in a new tab)
autoColorboolean | string-true, 80More Info (opens in a new tab)
autoContrastboolean | string-true, 80More Info (opens in a new tab)
assistColorblindboolean | string-true, 20, xrayMore Info (opens in a new tab)
blackwhiteboolean | string-true, 40More Info (opens in a new tab)
blurboolean | string-true, 800More Info (opens in a new tab)
blurFacesboolean | string-true, 800More Info (opens in a new tab)
blurRegionboolean | string-true, 1000,h_425,w_550,x_600,y_400More Info (opens in a new tab)
borderstring-5px_solid_purple
brightnessboolean | string-true, 100More Info (opens in a new tab)
brightnessHSBboolean | string-true, 100More Info (opens in a new tab)
cartoonifyboolean | string-true, 70:80More Info (opens in a new tab)
colorstring-blue
colorizestring-35,co_darkvioletMore Info (opens in a new tab)
contrastboolean | string-true, 100, level_-70More Info (opens in a new tab)
distortstring-150:340:1500:10:1500:1550:50:1000, arc:180.0More Info (opens in a new tab)
fillLightboolean | string-true, 70:20More Info (opens in a new tab)
gammaboolean | string-true, 100More Info (opens in a new tab)
gradientFadeboolean | string-true, symmetric:10,x_0.2,y_0.4More Info (opens in a new tab)
grayscalebool-trueMore Info (opens in a new tab)
improveboolean | string-true, 50, indoorMore Info (opens in a new tab)
multiplybool-trueMore Info (opens in a new tab)
negatebool-trueMore Info (opens in a new tab)
oilPaintboolean | string-true, 40More Info (opens in a new tab)
opacitynumber/string-40More Info (opens in a new tab)
outlineboolean | string-true, 40, outer:15:200More Info (opens in a new tab)
overlaybool-trueMore Info (opens in a new tab)
pixelateboolean | string-true, 20More Info (opens in a new tab)
pixelateFacesboolean | string-true, 20More Info (opens in a new tab)
pixelateRegionboolean | string-true, 35,h_425,w_550,x_600,y_400More Info (opens in a new tab)
redeyeboolean | string-trueMore Info (opens in a new tab)
replaceColorstring-saddlebrown, 2F4F4F:20, silver:55:89b8edMore Info (opens in a new tab)
sanitizebooltrue if .svgtrue - Only applies to .svgMore Info (opens in a new tab)
saturationboolean | string-true, 70More Info (opens in a new tab)
screenbool-trueMore Info (opens in a new tab)
sepiaboolean | string-true, 50More Info (opens in a new tab)
shadowboolean | string-true, 50,x_-15,y_15More Info (opens in a new tab)
sharpenboolean | string-true, 100More Info (opens in a new tab)
shearstring-20.0:0.0More Info (opens in a new tab)
simulateColorblindboolean | string-deuteranopiaMore Info (opens in a new tab)
tintboolean | string-true, 100:red:blue:yellowMore Info (opens in a new tab)
trimboolean | string-true, 50:yellowMore Info (opens in a new tab)
unsharpMaskboolean | string-true, 500More Info (opens in a new tab)
vectorizeboolean | string-true, 3:0.5More Info (opens in a new tab)
vibranceboolean | string-true, 70More Info (opens in a new tab)
vignetteboolean | string-true, 30More Info (opens in a new tab)

Examples

Make an image black and white:

blackwhite: true

Pixelate an image:

pixelate: true

Sharpen an image:

sharpen: 50

View the Cloudinary docs (opens in a new tab) to see learn more about using effects.

Overlays & Underlays

Cloudinary gives you the ability to add layers above or below your primary asset using Overlays and Underlays.

NameTypeExample
overlaysarrayCustomizing Overlays & Underlays
textstringNext Cloudinary
underlaystringmy-public-id
underlaysarrayCustomizing Overlays & Underlays

Customizing Overlays & Underlays

Note: The API for Underlays is similar to Overlays except they do not support text.

NameTypeExample
appliedEffectsarrayeffects, added as applied transformation
effectsarrayeffects
positionobjectposition
publicIdstringmypublicid
textobject|stringNext Cloudinary or See text Below
urlstringhttps://.../image.jpg

Examples

Adding an overlay:

overlays: [{
  publicId: 'images/earth',
  position: {
    x: 50,
    y: 50,
    gravity: 'north_west',
  },
  appliedEffects: [
    {
      multiply: true
    }
  ]
}]

Adding an underlay:

underlays: [{
  publicId: 'images/earth',
}]
effects

Objects in the effects array can include everything in Basic Transformations and Filters & Effects above as well as:

NameTypeExample
aspectRatiostring3.0More Info (opens in a new tab)
cropstring10More Info (opens in a new tab)
gravitystringnorth_westMore Info (opens in a new tab)
heightnumber600More Info (opens in a new tab)
widthnumber600More Info (opens in a new tab)
position

The position property can include:

NameTypeExample
anglenumber45More Info (opens in a new tab)
gravitystringnorth_westMore Info (opens in a new tab)
xnumber10More Info (opens in a new tab)
ynumber10More Info (opens in a new tab)
text

The text property can include:

NameTypeExample
borderstring20px_solid_blueMore Info (opens in a new tab)
colorstringbluevioletMore Info (opens in a new tab)
fontFamilystringOpen SansMore Info (opens in a new tab)
fontSizenumber48More Info (opens in a new tab)
fontWeightstringboldMore Info (opens in a new tab)
letterSpacingnumber14More Info (opens in a new tab)
lineSpacingnumber14More Info (opens in a new tab)
strokebooltrue in coordination with BorderMore Info (opens in a new tab)
textDecorationstringunderlineMore Info (opens in a new tab)

Advanced

Configuration & Delivery

NameTypeDefaultExample
assetTypestringimagevideoMore Info (opens in a new tab)
configobject-{ url: { secureDistribution: 'spacejelly.dev' } }More Info (opens in a new tab)
deliveryTypestringuploadfetchMore Info (opens in a new tab)
defaultImagestring-myimage.jpgMore Info (opens in a new tab)
flagsarray-['keep_iptc']More Info (opens in a new tab)
seoSuffixstring-my-image-contentMore Info (opens in a new tab)
versionnumber-1234More Info (opens in a new tab)

assetType

Configures the asset type for the delivered resource.

This defaults to an image for the getCldImageUrl helper.

Examples

Create an image thumbnail from a video asset:

assetType: 'video'

Learn more about Asset Types (opens in a new tab) on the Cloudinary docs.

config

Allows configuration for the Cloudinary environment.

Examples

config: {
  cloud: {
    cloudName: 'my-cloud'
  }
}

Learn more about configuration parameters (opens in a new tab) on the Cloudinary docs.

deliveryType

Controls the delivery type of the image.

Examples

deliveryType: 'fetch'

Learn more about Delivery Types (opens in a new tab) on the Cloudinary docs.

defaultImage

Configures the default image to use in case the given public ID is not available.

defaultImage must include a format / file extension.

Examples

defaultImage: 'myimage.jpg'

Learn more about Default Images (opens in a new tab) on the Cloudinary docs.

flags

Alters the regular behavior of another transformation or the overall delivery behavior.

The keep_iptc flag requires not including a quality of auto. Using quality="default" avoids setting the quality flag in the URL.

Examples

flags: ['keep_iptc'],
quality: 'default'

Learn more about Flags (opens in a new tab) on the Cloudinary docs.

seoSuffix

Adds a dynamic, descriptive suffix to the Public ID for greater SEO control of image URLs.

Examples

seoSuffix: 'jellyfish-in-space'

Learn more about Dynamic SEO Suffixes (opens in a new tab) on the Cloudinary docs.

version

Controls the version defined in the delivery URL.

Examples

version: '1234'

Learn more about Asset Versions (opens in a new tab) on the Cloudinary docs.

Managing Transformations

Most transformations and effects are exposed as top-level props to enable you to easily apply what you need, but you can also use the following props for more advanced and organized ways of applying transformations and effects.

NameTypeDefaultExample
effectsarray-[{ background: 'blue' }]
namedTransformationsstring | array-['my-named-transformation']More Info (opens in a new tab)
preserveTransformationsstringfalsetrue
rawTransformationsarray-['e_blur:2000']
strictTransformationsboolean-Strict TransformationsMore Info (opens in a new tab)
transformations (deprecated)string | array-['my-named-transformation']More Info (opens in a new tab)

effects

Applies a chain of transformation sets to an image.

Examples

effects: [
  {
    width: 100,
    height: 100,
    crop: 'fill'
  },
  {
    opacity: 50
  }
]

namedTransformations

Applies named transformations to the image.

Examples

namedTransformations: ['my-transformation']

Learn more about Named Transformations (opens in a new tab) on the Cloudinary docs.

preserveTransformations

Preserves transformations already applied to an image when passing in a Cloudinary URL as the src.

Examples

preserveTransformations: true

rawTransformations

Provides the ability to pass in an array of "raw" Cloudinary transformations using the Transformation URL API (opens in a new tab)

Examples

rawTransformations: ['w_100', 'b_blue', 'f_auto']

strictTransformations

Strict Transformations (opens in a new tab) gives you the ability to have more control over what transformations are permitted to be used from your Cloudinary account.

By enabling Strict Transformations, you restrict the ability to generate transformations on-the-fly requiring explicit approval through the Cloudinary dashboard.

Note: This disables optimization and responsive sizing only allowing named transformations to be applied. The width and height are not applied to the URL, but are still included on the image tag rendered to the DOM.

Examples

strictTransformations: true,
transformations: ['my-transformation']

Learn more about Strict Transformations (opens in a new tab) on the Cloudinary docs.

transformations - Deprecated

Use namedTransformations instead

Optimization

By default, getCldImageUrl opts in any image to f_auto and q_auto which provide automatic optimization through intelligent compression and by automatically delivering the most efficient format based on the browser and device requesting the image.

You can customize and manage these properties using the options below:

NameTypeDefaultExample
dprnumber/string-2.0More Info
formatstringautowebpMore Info
qualitystringauto90More Info
unoptimizedboolean-Unoptimized ImagesMore Info

dpr

Sets the device pixel ratio (DPR) for the delivered image or video using a specified value or automatically based on the requesting device.

Examples

dpr: '2.0'

Learn more about configuring DPR (opens in a new tab) on the Cloudinary docs.

format

Converts (if necessary) and delivers an asset in the specified format regardless of the file extension used in the delivery URL.

Examples

format: 'png'

Learn more about format (opens in a new tab) on the Cloudinary docs.

quality

Controls the quality of the delivered asset. Reducing the quality is a trade-off between visual quality and file size.

Examples

quality: 10

Learn more about quality (opens in a new tab) on the Cloudinary docs.