Getting Started with CldImage

The CldImage component provides an easy way to deliver images from Cloudinary in an Astro app.

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

As CldImage is a wrapper around the Unpic Image component, you also gain access to built-in Image component features that will work out-of-the-box like Responsive Sizing.

CldImage also allows you to use all of the standard HTML img attributes as props. See the Image Performance and LCP guide for guidance on how and when to use the standard loading and fetchpriority attributes, which should be applied to critical, above-the-fold images.

Basic Usage

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

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
  alt="<Description>"
  sizes="100vw" // Optional
/>

• Expand Snippet
• Collapse Snippet

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.

Tip

For images critical to page load like hero images or other above-the-fold content, consider adding fetchpriority="high" and loading="eager" to improve your Largest Contentful Paint (LCP). Learn more about Image Performance & LCP.

Transformations

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

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
  crop={{
    type: 'fill',
    source: true
  }}
  replaceBackground="cartoon outer space"
  overlays={[
    {
      position: {
        y: 40,
        x: -10,
        gravity: 'south',
      },
      text: {
        color: 'magenta',
        fontFamily: 'Source Sans Pro',
        fontSize: 160,
        fontWeight: 'black',
        text: 'OUT OF THIS WORLD'
      }
    },
    {
      position: {
        y: 50,
        gravity: 'south',
      },
      text: {
        color: 'white',
        fontFamily: 'Source Sans Pro',
        fontSize: 160,
        fontWeight: 'black',
        text: 'OUT OF THIS WORLD'
      }
    },
  ]}
  alt="<Description>"
  sizes="100vw"
/>

• 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 { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="https://res.cloudinary.com/mycloud/image/upload/v1234/myimage"
  width="<Width>"
  height="<Height>"
  alt="<Description>"
/>

• Expand Snippet
• Collapse Snippet

Preserving URL Transformations

If using a full Cloudinary URL, you might already have transformations applied to your image.

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

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="https://res.cloudinary.com/<Cloud Name>/image/upload/w_100,h_200,c_fill/v1234/myimage"
  width="<Width>"
  height="<Height>"
  preserveTransformations
  alt="<Description>"
/>

• Expand Snippet
• Collapse Snippet

For example:

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="https://res.cloudinary.com/<Cloud Name>/image/upload/e_background_removal/b_blueviolet/f_auto/q_auto/v1/cld-sample-5"
  width="<Width>"
  height="<Height>"
  preserveTransformations
  alt="test"
/>

• Expand Snippet
• Collapse Snippet

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

Image Events

The CldImage component actively triggers a single Error event as a CustomEvent in order to allow callback functionality if there is something wrong in how the image loads.

Caution

This image is intended to be broken for demonstration purposes!

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  id="image-events"
  src="this-image-does-not-exist"
  width="<Width>"
  height="<Height>"
/>

<script>
const image = document.querySelector(`#image-events`);

if ( image ) {
  image.addEventListener('cldimage:error', ((e: CustomEvent<{ detail: {} }>) => {
    console.log('cldimage:error', e.detail)
  }) as EventListener);
};
</script>

• Expand Snippet
• Collapse Snippet

Tip

See your browser’s web console to preview the information logged in the above callback.

Learn More about CldImage

• Configuration
• Examples