Astro Images — Automatic Image Optimization

In this tutorial, you will learn about Astro Images. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Astro image optimization: use the Image component, optimize remote images, generate responsive srcsets, and lazy load for performance.

In this lesson, you'll configure the Astro image service, use the <Image /> and <Picture /> components, optimize remote images, and implement Lazy Loading.

What You'll Learn

How to install and configure the image integration, use the <Image /> component for optimization, handle remote images, and generate responsive image sets.

Why It Matters

Images are the largest contributor to page weight. Astro's image optimization automatically generates multiple sizes and formats, reducing load times and improving Core Web Vitals.

Real-World Use

DodaTech's documentation site uses Astro images for tutorial screenshots, automatically generating WebP and AVIF formats with appropriate sizes for each device.

flowchart LR
    A[Source Image] --> B[Astro Image Service]
    B --> C[WebP]
    B --> D[AVIF]
    B --> E[Multiple Widths]
    C --> F[Responsive Output]
    style B fill:#ff5a03,color:#fff

Setup

Install the image integration:

npx astro add image

This adds @astrojs/image to your config and installs Sharp for image processing.

Using the Image Component

---
import { Image } from "@astrojs/image/components";
import heroImage from "../images/hero.jpg";
---
<Image
  src={heroImage}
  alt="Hero banner"
  width={1200}
  height={600}
  format="webp"
  loading="lazy"
/>

Output: Astro generates WebP versions of the image at optimal sizes, adds a <picture> element with responsive sources, and includes lazy loading attributes.

Remote Images

Optimize images from external URLs:

---
import { Image } from "@astrojs/image/components";
---
<Image
  src="https://example.com/image.jpg"
  alt="Remote image"
  width={800}
  height={500}
  formats={["webp", "avif"]}
/>

Output: Astro downloads the remote image at build time, optimizes it, and serves the optimized local version.

The Picture Component

Use <Picture /> for art direction:

---
import { Picture } from "@astrojs/image/components";
import desktopImg from "../images/desktop.jpg";
import mobileImg from "../images/mobile.jpg";
---
<Picture
  src={desktopImg}
  alt="Responsive image"
  widths={[400, 800, 1200]}
  sizes="(max-width: 768px) 100vw, 50vw"
  formats={["avif", "webp"]}
  fallbackFormat="jpeg"
/>

Output: Generates multiple formats and sizes with a <picture> element that serves different images based on viewport width.

Image in Content Collections

Use z.image() in collection schemas:

import { defineCollection, z } from "astro:content";

const galleryCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    image: z.image(),
    thumbnail: z.image().optional(),
  }),
});

In frontmatter:

---
title: Gallery Item
image: "./images/photo.jpg"
---

Astro validates the image exists and optimizes it automatically.

Common Mistakes

1. Not installing Sharp: The image integration requires Sharp. Install it with npm install sharp.
2. Forgetting alt text: The alt attribute is required for Accessibility. Omitting it causes accessibility violations.
3. Using raw <img> tags: Raw <img> tags skip optimization. Always use the <Image /> or <Picture /> component.
4. Not specifying widths: Without explicit widths or a widths array, Astro uses defaults that may not match your layout.
5. Over-optimizing small images: Icons and small decorative images don't need multiple formats. Use a standard <img> for them.

Practice Questions

1. What does the <Image /> component do? Answer: It optimizes images by generating multiple formats and sizes, adding responsive srcsets, and enabling lazy loading.

2. How do you optimize remote images? Answer: Pass the remote URL as the src prop. Astro downloads and optimizes it at build time.

3. What is the <Picture /> component used for? Answer: Art direction—serving different images at different viewport sizes for Responsive Design.

4. Why use formats instead of a single format? Answer: Multiple formats let the browser choose the best supported one (AVIF first, then WebP, then JPEG fallback).

Challenge

Build a responsive image gallery that serves different image sizes for mobile, tablet, and desktop. Use the <Picture /> component with art direction breakpoints.

Mini Project

Create a product page with a hero image using <Image /> (1200px, WebP), a thumbnail grid using <Image /> with lazy loading, and a zoom feature that links to the full-resolution original.

FAQ

What's Next

Learn how to manage Astro Fonts for custom typography with automatic optimization.