Astro Picture Component: adding Responsive Images
Tags: astro, optimization, webdev
Published: 2023-11-13 17:43:35

---
title: "Astro Picture Component: adding Responsive Images"
published: "true"
description: "Astro Picture Component 🖼️ using Astro in-built tooling to add next-gen (WebP & AVIF), responsive images to your 🚀 Astro Markdown blog."
tags: "astro, optimization, webdev"
canonical_url: "https://rodneylab.com/astro-picture-component/"
cover_image: "https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gtbu93m4dsdppma7rq9y.png"
---

## 🚀 Adding Responsive Images to Astro Blog Posts

Let&rsquo;s take  a look at the built-in Astro Picture component. Astro Content Collections offer a fantastic Developer Experience for building **Markdown** blog or **documentation sites**, but did you know how well they dovetail with the Picture component?

The Astro Picture component does the heavy lifting in adding responsive image markup to your content sites.  If you have ever had to construct HTML `<picture>` tags from scratch, you will know supporting devices with different capabilities and screen-sizes in a **performant** way is not easy.

Usually with responsive images, we mean serving large, double pixel density images, for users with **Retina displays**, but dialling down the resolution for a user on a smaller mobile device, which is able to make the image look equally sharp with a fraction of the pixels.

### Responsive and Next-gen Images

Sending the right sized image for the user device, reduces the number of bytes streamed.  Another popular way of reducing shipped image bytes is using **WebP** and **AVIF** images.  These next-gen formats should encode images more efficiently, allowing for smaller files, though older devices do not support them.

## 😕 The Astro Picture Component

The HTML `<picture>` tag, essentially, is a way of communicating to the browser which formats you have available on the server and in what sizes, and letting the browser pick the most suitable one.  You can imagine, adding this much detail for each image can become cumbersome.  And we haven&rsquo;t even mentioned adding markup to prevent Cumulative Layout Shift (**CLS**) yet!

The Astro Picture component is designed to help you here, saving you from having to construct that HTML `<picture>` tag yourself.  In this post, we see how you can work with the Astro Picture component to add a banner image to each post on a blog site.  As a bonus, we also look at using Astro Content Collections, to generate a low-resolution placeholder image to display while the banner image is loading.

## 🧱 What are we Building?

Instead of building a new blog from start-to-finish, we&rsquo;ll just see the steps you need to add banner images to blog posts to an existing Astro Markdown site with <a href="https://docs.astro.build/en/guides/content-collections/">Content Collections</a>.  There is a link to the complete project code further down the page.

## 👮🏽 Content Collections

Content collections are invaluable for making sure your content Markdown front matter has all the fields you need it to have.  The <a href="https://zod.dev/">schema uses `zod` under the hood</a>, so you might already be familiar with the syntax.  Here, we will see how you can also use the schema to generate the image metadata needed for use with Astro&rsquo;s Picture component.

```markdown
---
postTitle: 'Best Medium Format Camera for Starting Out'
datePublished: '2023-10-07T16:04:42.000+0100'
lastUpdated: '2022-10-23T10:17:52.000+0100'
featuredImage: './best-medium-format-camera-for-starting-out.jpg'
featuredImageAlt: 'Photograph of a Hasselblad medium format camera with the focusing screen exposed'
---

## What is a Medium Format Camera?

If you are old enough to remember the analogue film camera era, chances are it is the 35&nbsp;mm canisters with the track cut down the side that first come to mind. Shots normally...
```

The first step is to place the banner image in the content folder, within your Astro project.  Here, I copied the image I want to use to the same directory as the Markdown file containing the post content.

Then, above, you can see I added a `featuredImage` field to the post front matter, with the path to the image (path is relative to the Markdown file&rsquo;s own path, `src/content/posts/best-medium-format-camera-for-starting-out/index.md`).  Equally important is the image alt text (in line `6`), which we also want to feed into the Astro Picture component.

### Schema File

The next change is to the schema file (at `src/content/config.ts`).  A schema is not required for using Content Collections generally, though you will need one to generate the image meta.  See `zod` docs for explanation of anything that you are not familiar with, or drop a question below in the comments.

```typescript
import { defineCollection, z } from 'astro:content';

const postsCollection = defineCollection({
	type: 'content',
	schema: ({ image }) =>
		z.object({
			postTitle: z.string(),
			datePublished: z.string(),
			lastUpdated: z.string(),
			featuredImage: image(),
			featuredImageAlt: z.string(),
			ogImage: z.string().optional(),
			draft: z.boolean(),
		}),
});

export const collections = {
	posts: postsCollection,
};
```

For Astro to generate the image metadata, just include the image function as an argument to the callback in line `5`, and call that same function on the `featuredImage` field.  If you include multiple image fields in the front matter, you can call `image` on each.

Calling `image` automatically generates the following fields for the picture, which we use in the next section:

```typescript
const featuredImage: {
    src: string;
    width: number;
    height: number;
    format: "png" | "jpg" | "jpeg" | "tiff" | "webp" | "gif" | "svg" | "avif";
}
```
## 🧩 Adding the Astro Picture Component

The final missing piece of the puzzle is pulling in the metadata generated in the schema to an instance of the Astro Picture component.  The first step, then, is to extract that metadata within the front matter section of the blog post page template (`src/pages/[slug].astro`):

```astro
---
import { Picture } from 'astro:assets';
import type { CollectionEntry } from 'astro:content';
import { getCollection } from 'astro:content';
import BaseLayout from '~layouts/BaseLayout.astro';

export async function getStaticPaths() {
	const posts = await getCollection('posts');
	return posts.map(
		({
			data: { featuredImage, featuredImageAlt, postTitle },
			render,
			slug,
		}) => {
			return {
				params: { slug },
				props: {
					featuredImage,
					featuredImageAlt,
					render,
					postTitle,
				},
			};
		},
	);
}

type PostCollection = CollectionEntry<'posts'>;
type Props = Pick<
	PostCollection['data'],
	'featuredImage' | 'featuredImageAlt' | 'seoMetaDescription' | 'placeholder' | 'postTitle'
> &
	Pick<PostCollection, 'render'>;

const { slug } = Astro.params;
const {
	featuredImage,
	featuredImageAlt,
	render,
	postTitle: title,
}: Props = Astro.props;

const { Content } = await render();

const { format, width, height } = featuredImage;
---
```

### Adding the Picture Component to Astro Markup

To finish off, let&rsquo;s add the Astro Picture component to the markup:

```astro
---
// TRUNCATED...
---

<BaseLayout {...seoProps}>
	<h1>{title}</h1>
	<div class="image-wrapper">
		<Picture
			src={featuredImage}
			alt={featuredImageAlt}
			densities={[1.5, 2]}
			formats={['avif', 'webp']}
			fallbackFormat={format}
			loading="eager"
			fetchpriority="high"
		/>
	</div>

	<div class="container">
		<Content />
	</div>
</BaseLayout>
```

- We imported the Picture from `astro:assets` in line `2` of the front matter.
- The component has the attributes you expect on a regular HTML `img` tag, such as `src`, `alt` and `loading`.
- For most images, `loading` will be `lazy`, <a href="https://web.dev/articles/browser-level-image-lazy-loading">to optimize page load. Generally, though, for a banner image or other large contentful object initially displayed, you will pick `eager`</a>, and also, to set `fetchpriority` to `high`.

Notice, we also have `densities`, `formats` and `fallbackFormat` props.  These are used to generate the final HTML `<picture>` tag.

- `densities` are the pixel densities used for high resolution screens, like Retina displays, typically `1.5` and `2` will be just fine here.
- `formats` are the next-gen formats you want the images available in. To be safe, you might choose just `webp` as <a href="https://docs.imgix.com/apis/rendering/auto/auto#format">there have been issues with displaying some `avif` images in Safari</a>. An alternative is to use <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation">content negotiation</a>.
- `fallbackFormat` this is the format you want older browsers to use (browsers which do not support WebP or AVIF), and is probably the format of the original image.

### Generated HTML Markup

<Image client:load {...imageProps[0]} />

Using the above parameters, the final markup looks something like this:

```html
<picture
  ><source
    srcset="
      /_astro/best-medium-format-camera-for-starting-out.8696310b_Zzixeg.avif,
      /_astro/best-medium-format-camera-for-starting-out.8696310b_Zzixeg.avif 1.5x,
      /_astro/best-medium-format-camera-for-starting-out.8696310b_Zzixeg.avif 2x
    "
    type="image/avif" />
  <source
    srcset="
      /_astro/best-medium-format-camera-for-starting-out.8696310b_Oo3Ed.webp,
      /_astro/best-medium-format-camera-for-starting-out.8696310b_Oo3Ed.webp 1.5x,
      /_astro/best-medium-format-camera-for-starting-out.8696310b_Oo3Ed.webp 2x
    "
    type="image/webp" />
  <img
    src="/_astro/best-medium-format-camera-for-starting-out.8696310b_1MPGLA.jpg"
    srcset="
      /_astro/best-medium-format-camera-for-starting-out.8696310b_1MPGLA.jpg 1.5x,
      /_astro/best-medium-format-camera-for-starting-out.8696310b_1MPGLA.jpg 2x
    "
    alt="Photograph of a Hasselblad medium format camera with the focusing screen exposed"
    loading="eager"
    data-astro-cid-yvbahnfj=""
    width="1344"
    height="896"
    decoding="async"
/></picture>
```

Notice the image URLs include a hash in the path, which is ideal for <a href="https://rodneylab.com/deno-fresh-svg-sprites/">cache-busting</a>.

## 🏆 Level it up: Low Resolution Placeholder

You might not have known it is possible to transform front matter fields within the Content Collection schema file.  We can use this feature to generate low resolution placeholders automatically, using the <a aria-label="Thumb Hash algorithm" href="https://evanw.github.io/thumbhash/">ThumbHash algorithm</a>.

To start, let&rsquo;s add a placeholder field to the front matter:

```markdown
---
postTitle: 'Best Medium Format Camera for Starting Out'
datePublished: '2023-10-07T16:04:42.000+0100'
lastUpdated: '2022-10-23T10:17:52.000+0100'
featuredImage: './best-medium-format-camera-for-starting-out.jpg'
featuredImageAlt: 'Photograph of a Hasselblad medium format camera with the focusing screen exposed'
placeholder: 'best-medium-format-camera-for-starting-out/best-medium-format-camera-for-starting-out.jpg'
---
```

To avoid using undocumented Astro APIs (which might later change), I have included the post folder name in the path here. This is different to how we added the featured image itself.

Next, we can add the transformation to our schema (`src/content/config.ts`):

```typescript
import { image_placeholder } from '@rodneylab/picpack';
import { defineCollection, z } from 'astro:content';
import { readFile } from 'node:fs/promises';

const postsCollection = defineCollection({
	type: 'content',
	schema: ({ image }) =>
		z.object({
			postTitle: z.string(),
			datePublished: z.string(),
			lastUpdated: z.string(),
			featuredImage: image(),
			featuredImageAlt: z.string(),
			ogImage: z.string().optional(),
			placeholder: z.string().transform(async (value) => {
				const { buffer } = await readFile(`./src/content/posts/${value}`);
				const imageBytes = new Uint8Array(buffer);
				const { base64 } = image_placeholder(imageBytes);
				return base64;
			}),
			draft: z.boolean(),
		}),
});

export const collections = {
	posts: postsCollection,
};
```

Here, I added a Rust WASM helper package (<a href="https://www.npmjs.com/package/@rodneylab/picpack">@rodneylab/picpack</a>) to generate the placeholder using ThumbHash.  The arrow function in the `placeholder` field (lines `15`-`19`) reads the bytes from the image and generates a Base64-encoded placeholder.  We took the image path and transformed the field to make a placeholder Base64-encoded string available in the Astro page template.

### Placeholder Markup

```astro
---
// TRUNCATED...
---

<BaseLayout {...seoProps}>
	<h1>{title}</h1>
	<div class="image-wrapper">
		<img class="placeholder" aria-hidden="true" src={placeholder} width={width} height={height} />
		<Picture
			pictureAttributes={{ class: 'image lazy' }}
			src={featuredImage}
			alt={featuredImageAlt}
			densities={[1.5, 2]}
			formats={['avif', 'webp']}
			fallbackFormat={format}
			loading="eager"
			fetchpriority="high"
		/>
	</div>

	<div class="container">
		<Content />
	</div>
</BaseLayout>
```
We have an extra `<img>` element, which will contain the placeholder.  Its `src` is the Base64 placeholder, which we just generated in the schema transformation.  Notice in line `60`, the `pictureAttributes` prop lets us add a class to the generated `<picture>` tag.

The final missing piece is a spot of CSS to place the full-scale image on top of the placeholder, so that it displays (over the placeholder) as soon as it loads:

```css
img,
picture {
	display: block;
	max-width: 100%;
	height: auto;
}

.image-wrapper {
	display: grid;

	.placeholder,
	.image {
		display: block;
		grid-area: 1/1/1/1;
		height: auto;
		aspect-ratio: 3/2;
	}
}
```

You can go to town on this, adding a touch of JavaScript to blend the placeholder into the full-scale image once it is loaded, though we won&rsquo;t get into that here.


## Astro Picture Component Alternatives

Hopefully, this has given you an idea of how the Astro Picture component works, and whether it will be suitable for your own project.  You might also <a href="https://unpic.pics/img/astro/"">consider the `unpic` project as an alternative</a>.  It is designed to work with hosting services (such as Imgix), and has an Astro-specific image component.

You can also roll your own.  The <a href="https://sharp.pixelplumbing.com/">sharp image plugin</a> is a good starting point.  It is performant, and runs in environments other than Node.js: Deno and Bun, for example.

## 🙌🏽 Astro Picture Component: Wrapping Up

In this post, we saw how you can add responsive banner images to your Astro blog Markdown posts.  In particular, we saw:

- how you can **automatically generate image metadata** using Content Collection schema;
- how you can transform front matter fields to **generate Base64 placeholder images** from image paths; and
- some options available on the Picture element to control the generation of **next-gen AVIF and WebP alternatives** for devices of different display sizes.

You can see the <a href="https://github.com/rodneylab/astro-blog-markdown">full code for this project in the Rodney Lab GitHub repo</a>.  I do hope you have found this post useful! Let me know how you add pictures to your site, whether you use the Astro Picture components, go for unpic with a hosting service or build something more manual.  Also, let me know about any possible improvements to the content above.


## 🙏🏽 Astro Picture Component: Feedback

Have you found the post useful? Would you prefer to see posts on another topic instead? Get in touch with ideas for new posts. Also, if you like my writing style, get in touch if I can write some posts for your company site on a consultancy basis. Read on to find ways to get in touch, further below. If you want to support posts similar to this one and can spare a few dollars, euros or pounds, please <a aria-label="Support Rodney Lab via Buy me a Coffee" href="https://rodneylab.com/giving/">consider supporting me through Buy me a Coffee</a>.

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via <a href="https://twitter.com/messages/compose?recipient_id=1323579817258831875">@askRodney</a> on X, <a href="https://toot.community/@rodney">@rodney@toot.community</a> on Mastodon and also the <a aria-label="Contact Rodney Lab via Telegram" href="https://matrix.to/#/%23rodney:matrix.org">#rodney</a> Element Matrix room. Also, see <a aria-label="Get in touch with Rodney Lab" href="https://rodneylab.com/contact/">further ways to get in touch with Rodney Lab</a>. I post regularly on <a aria-label="See posts on Astro" href="https://rodneylab.com/tags/astro/">Astro</a> as well as <a aria-label="See posts on svelte kit" href="https://rodneylab.com/tags/seo/">SEO</a>. Also, <a aria-label="Subscribe to the Rodney Lab newsletter" href="https://newsletter.rodneylab.com/issue/latest-issue">subscribe to the newsletter to keep up-to-date</a> with our latest projects.