Configuring CldImage

The CldImage component provides a wide range of options for being able to easily optimize and transform images.

Required Props

The basic props required to use CldImage include:

Prop	Type	Required	Example
alt	string	Yes	Dog catching a frisbee	More Info
height	number/string	Yes	600	More Info
src	string	Yes	my-public-id
width	number/string	Yes	600	More Info

Basic Transformations

The CldImage component exposes many of Cloudinary’s transformations in an easy-to-use way right inside of Astro.

Prop	Type	Default	Example
angle	number		45	More Info
background	string	-	blue, rgb:0000ff	More Info
crop	string | object	limit	fill	More Info
enhance	boolean	-	true	More Info
fillBackground (Beta)	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 at the given angle.

Examples

angle={15}

Learn more about angle on the Cloudinary docs.

background

Applies a background to empty or transparent areas.

Examples

background="blue"

Learn more about the background transformation 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, or it can accept an object or an array of objects which can take 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
zoom	string	See 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 CldImage).

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.

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 on the Cloudinary docs.

enhance

Tip

Generative Enhance is currently in beta.

Uses generative AI to enhance the visual appeal of an image.

The enhance prop can be used as a boolean.

Examples

enhance

Learn more about the Generative Enhance transformation on the Cloudinary docs.

fillBackground

Tip

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:

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

Examples

Applying Generative Fill with defaults:

fillBackground

Customizing options:

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

Learn more about the Generative Fill transformation 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 on the Cloudinary docs.

loop

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

Examples

loop

Learn more about loop on the Cloudinary docs.

recolor

Tip

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:

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

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 on the Cloudinary docs.

remove

Tip

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:

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:

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 on the Cloudinary docs.

removeBackground

Uses the Cloudinary AI Background Removal add-on to make the background of an image transparent.

Note

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

Examples

removeBackground

Learn more about background removal transformation on the Cloudinary docs.

replace

Tip

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:

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

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 on the Cloudinary docs.

replaceBackground

Tip

Generative Replace Background is currently in beta.

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:

replaceBackground

Or using a string prompt:

replaceBackground="fish tank"

Or using the object format:

replaceBackground={{
  prompt: 'fish tank',
  seed: 3
}}

Learn more about the Generative Replace Background transformation on the Cloudinary docs.

restore

Tip

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

Learn more about the Generative Restore transformation 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 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:

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

Examples

With defaults:

zoompan

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 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.

Prop	Type	Default	Example
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

Examples

Make an image black and white:

blackwhite

Pixelate an image:

pixelate

Sharpen an image:

sharpen={50}

View the Cloudinary docs 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.

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

Customizing Overlays & Underlays

Tip

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

Prop	Type	Example
appliedEffects	array	effects, added as applied transformation
effects	array	effects
position	object	position
publicId	string	mypublicid
text	object|string	Astro Cloudinary or See text Below
url	string	https://.../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:

Prop	Type	Example
aspectRatio	string	3.0	More Info
crop	string	10	More Info
gravity	string	north_west	More Info
height	number	600	More Info
width	number	600	More Info

position

The position property can include:

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

text

The text property can include:

Prop	Type	Example
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

Advanced

Configuration & Delivery

Prop	Type	Default	Example
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

Configures the asset type for the delivered resource.

This defaults to an image for the CldImage component.

Examples

Create an image thumbnail from a video asset:

assetType="video"

Learn more about Asset Types on the Cloudinary docs.

config

Allows configuration for the Cloudinary environment.

Examples

config={{
  cloud: {
    cloudName: '<Your Cloud Name>',
  }
}}

Learn more about configuration parameters on the Cloudinary docs.

deliveryType

Controls the delivery type of the image.

Examples

deliveryType="fetch"

Learn more about Delivery Types on the Cloudinary docs.

defaultImage

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

Tip

defaultImage must include a format / file extension.

Examples

defaultImage="myimage.jpg"

Learn more about Default Images on the Cloudinary docs.

flags

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

Tip

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 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 on the Cloudinary docs.

version

Controls the version defined in the delivery URL.

Examples

version="1234"

Learn more about Asset Versions 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.

Prop	Type	Default	Example
effects	array	-	[{ background: 'blue' }]
namedTransformations	string | array	-	['my-named-transformation']	More Info
preserveTransformations	string	false	true
rawTransformations	array	-	['e_blur:2000']
strictTransformations	boolean	-	Strict Transformations	More Info
transformations (deprecated)	string | array	-	['my-named-transformation']	More Info

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 on the Cloudinary docs.

preserveTransformations

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

Tip

The Cloudinary URL requires a version number (ex: /v1234/) in order to be parsed.

When using this option, the transformations will be parsed from a valid URL and then be applied as rawTransformations.

Examples

preserveTransformations

rawTransformations

Provides the ability to pass in an array of “raw” Cloudinary transformations using the Transformation URL API.

When using this option, if a format (f_) or quality (q_) is detected in the applied transformations, the respective option will not be applied automatically unless explicitly configured on the component using the format or quality options.

Examples

rawTransformations={['w_100', 'b_blue', 'f_auto']}

strictTransformations

Strict Transformations 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.

Tip

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
transformations=["my-transformation"]

Learn more about Strict Transformations on the Cloudinary docs.

Optimization

By default, CldImage 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:

Prop	Type	Default	Example
dpr	number/string	-	2.0	More Info
format	string	auto	webp	More Info
quality	string | number	auto	90	More 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 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 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 on the Cloudinary docs.