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.

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.

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