CldImage Configuration

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

Note: Configuration for CldImage is the same as getCldImageUrl, which both use the same underlying API.

Required Props

The basic props required to use CldImage include:

Unpic Image Props

CldImage extends the Unpic Image component using Cloudinary tech. This means all props available on the Unpic Image component are available on CldImage. Learn more on the Unpic Docs.

Basic Transformations

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

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.

Examples

crop = 'fill';

Learn more about the crop 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:

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.

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:

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

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:

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.

Examples

removeBackground;

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:

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.

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

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:

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.

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.

Customizing Overlays & Underlays

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

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',
}]}

Advanced

Configuration & Delivery

config

Allows configuration for the Cloudinary environment.

Examples

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

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.

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.

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.

Events & Refs

onError

Callback that fire when an image fails to load.

Upon failure, if the resulting HTTP status is a 423 (Processing), CldImage will attempt to poll the URL until it’s available, then force refresh the image instance in the DOM.

Examples

onError={() => {
  alert('Image failed to load!')
}}

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.

effects

Applies a chain of transformation sets to an image.

Examples

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

preserveTransformations

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

Examples

preserveTransformations;

rawTransformations

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

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.

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

Learn more about Strict Transformations on the Cloudinary docs.

transformations

Applies named transformations to the image.

Examples

transformations={['my-transformation']}

Learn more about Named 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:

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.