Image gallery with Astro and Cloudinary (video tutorial)

Overview

Learn how to build an image gallery in Astro by sourcing assets directly from your Cloudinary Media Library using the Astro content layer. This tutorial shows how to use the cldAssetsLoader from the Astro Cloudinary community-developed library to define a Cloudinary collection, fetch assets with getCollection, and display them using the CldImage component with automatic format optimization, responsive sizing, and AI-powered smart cropping.

Video tutorial

Tutorial contents

This tutorial presents the following topics. Click a timestamp to jump to that part of the video.

Introduction

0:00	Astro's content layer can source content from many places, including Cloudinary. Using the cldAssetsLoader from the Astro Cloudinary community-developed library, you can define a collection that pulls images and videos directly from your Cloudinary media library.

Defining a Cloudinary collection

0:48	In your Astro project's src/content/config.ts file, define a collection using defineCollection from astro:content. Set the loader to cldAssetsLoader(), imported from astro-cloudinary/loaders. By default, the loader fetches all assets from the root of your Cloudinary account using the Admin API. Pass a folder name in the loader options to limit results to a specific folder.

Fetching assets in a page

2:10	In any Astro page or component, import getCollection from astro:content and call it with your collection name to fetch all assets. The returned data includes metadata for each asset from your Cloudinary account, such as public_id, secure_url, width, height, and more.

Displaying images

2:50	Loop through the fetched assets and render each image using a standard <img> tag with asset.data.secure_url as the source. Each asset object exposes useful metadata from Cloudinary's resource response, including dimensions, format, and tags, giving you full control over how images are displayed.

Customizing the loader

3:23	Because cldAssetsLoader uses the Admin API under the hood, you can pass a configuration object to customize what it fetches. Filter assets by folder (e.g., folder: "e-commerce/sneakers"), or request additional data such as contextual metadata, moderation status, and structured metadata fields, depending on what your project needs.

CLD Image component and transformations

3:50

Because your assets are sourced from Cloudinary, you can go a step further and apply image transformations directly in your Astro components. Import CldImage from astro-cloudinary and replace the <img> tag with it, using asset.data.public_id as the src. Pass width and height from the asset data for the correct aspect ratio. CldImage automatically applies f_auto and q_auto optimizations, delivering the best format and quality for each browser.

Responsive sizing

4:54	Add the sizes attribute to CldImage to define how wide the image should be at different viewport sizes. For example, a four-column grid might always display images at roughly 25% of the viewport width. Cloudinary uses this information to deliver only the pixels needed for each device, reducing bandwidth without sacrificing visual quality.

AI-powered smart cropping

5:18	Add a crop: "auto" transformation to CldImage to enable Cloudinary's AI-powered subject-aware cropping. Every image is cropped at the server level, not hidden with CSS, so you're never sending unnecessary pixels. Cloudinary's AI detects the most important subject or region in each photo and crops to preserve it.

Keep learning

If you like this, you might also like...

 

 

Check out the Cloudinary Academy for free self-paced Cloudinary courses on a variety of developer or DAM topics, or register for formal instructor-led courses, either virtual or on-site.