Getting Started with getCldImageUrl

The getCldImageUrl helper provides an easy way to generate image URLs from Cloudinary in an Astro app.

With it comes access to more advanced features like dynamic cropping, background removal, overlays, and other Cloudinary transformations.

getCldImageUrl is the API the powers CldImage, so usage works the same.

Basic Usage

The basic required props include width, height, src, and alt:

import { getCldImageUrl } from 'astro-cloudinary/helpers';

const url = getCldImageUrl({ src: '<Public ID>' });

The src property takes in a Cloudinary Public ID which includes the folder path along with the ID of the image itself. The width and the height should represent the rendered size and the alt value should be a text-based description of the image.

The sizes prop is optional, but recommended for Responsive Sizing.

Transformations

You can further take advantage of Cloudinary features like replacing backgrounds with generative AI and text overlays by adding additional props:

import { getCldImageUrl } from 'astro-cloudinary/helpers';

const url = getCldImageUrl({
  src: '<Public ID>'
  crop: {
    type: 'fill',
    source: true
  },
  replaceBackground: 'space',
});

• Expand Snippet
• Collapse Snippet

Check out more examples of what you can do with transformations!

Using Cloudinary URLs

CldImage supports passing a fully qualified Cloudinary URL as the src, however, it must include a version number (/v1234/) in order to be correctly parsed.

Note

The version number is required due to the variable nature of Cloudinary URLs. This helps to ensure the integretiy when during the parsing process.

import { getCldImageUrl } from 'astro-cloudinary/helpers';

const url = getCldImageUrl({
  src: 'https://res.cloudinary.com/mycloud/image/upload/v1234/myimage',
});

Preserving URL Transformations

When passing the result of getCldImageUrl to the CldImage component, it’s important to preserve any transformations, as by default, CldImage will only maintain the public ID of the URL provided.

To preserve those transformations, you can apply the preserveTransformations property to CldImage:

import { getCldImageUrl } from 'astro-cloudinary/helpers';

const url = getCldImageUrl({
  src: 'https://res.cloudinary.com/<Cloud Name>/image/upload/w_100,h_200,c_fill/v1234/myimage',
  preserveTransformations: true
});

For example:

import { getCldImageUrl } from 'astro-cloudinary/helpers';

const url = getCldImageUrl({
  src: 'https://res.cloudinary.com/<Cloud Name>/image/upload/e_background_removal/b_blueviolet/f_auto/q_auto/v1/cld-sample-5',
  preserveTransformations: true
})

Would generate a URL of:

https://res.cloudinary.com/<Cloud Name>/image/upload/e_background_removal/b_blueviolet/f_auto/q_auto/c_limit,w_1600/v1/cld-sample-5?_a=BBGAABS00

Learn More about getCldImageUrl

• Configuration
• Examples