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