Configuring getCldImageUrl
The getCldImageUrl helper provides a wide range of options for being able to easily optimize and transform images.
Required Props
The basic props required to use getCldImageUrl include:
Prop | Type | Required | Example | |
---|---|---|---|---|
src | string | Yes | my-public-id |
Basic Transformations
The getCldImageUrl 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
Learn more about angle on the Cloudinary docs.
background
Applies a background to empty or transparent areas.
Examples
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 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.
Examples
Cropping an image and filling the containing space:
Using a crop of thumb
on the original source image:
Learn more about the crop transformation on the Cloudinary docs.
enhance
Uses generative AI to enhance the visual appeal of an image.
The enhance
prop can be used as a boolean.
Examples
Learn more about the Generative Enhance transformation on the Cloudinary docs.
fillBackground
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:
Customizing options:
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
Learn more about gravity on the Cloudinary docs.
loop
Loops an animated image infinitely or for the specified number of times.
Examples
Learn more about loop on the Cloudinary docs.
recolor
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:
Or using the object format:
Learn more about the Generative Recolor transformation on the Cloudinary docs.
remove
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:
Removing multiple objects by array:
Removing multiple instances of an object and their shadow with object configuration:
Removing a region:
Removing multiple regions:
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.
Examples
Learn more about background removal transformation on the Cloudinary docs.
replace
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:
Or using the object format:
Learn more about the Generative Replace transformation on the Cloudinary docs.
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:
Or using a string prompt:
Or using the object format:
Learn more about the Generative Replace Background transformation on the Cloudinary docs.
restore
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
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
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:
Add looping:
Customize options:
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:
Pixelate an image:
Sharpen an image:
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
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:
Adding an underlay:
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 getCldImageUrl helper.
Examples
Create an image thumbnail from a video asset:
Learn more about Asset Types on the Cloudinary docs.
config
Allows configuration for the Cloudinary environment.
Examples
Learn more about configuration parameters on the Cloudinary docs.
deliveryType
Controls the delivery type of the image.
Examples
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.
Examples
Learn more about Default Images on the Cloudinary docs.
flags
Alters the regular behavior of another transformation or the overall delivery behavior.
Examples
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
Learn more about Dynamic SEO Suffixes on the Cloudinary docs.
version
Controls the version defined in the delivery URL.
Examples
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
namedTransformations
Applies named transformations to the image.
Examples
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
.
When using this option, the transformations will be parsed from a valid URL and then be applied as rawTransformations.
Examples
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
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.
Examples
Learn more about Strict Transformations on the Cloudinary docs.
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:
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
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
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
Learn more about quality on the Cloudinary docs.