Images

Astro ships an <Image /> component that resizes, compresses, and re-encodes source images at build time — and sets width/height so there’s no layout shift.

The Basics

---
import { Image } from "astro:assets";
import hero from "../assets/hero.jpg";
---

<Image src={hero} alt="Mountains at sunset" width={1200} />

• src — an imported image (gets typed dimensions)
• alt — required by the type system
• width / height — optional; if omitted, Astro uses the source dimensions

The output: a sized, format-converted (WebP / AVIF) version of the source.

Source Location

Imported images live in src/, NOT public/:

src/
├── assets/
│   └── hero.jpg     ← optimized by Astro
└── components/

public/
└── og-image.png     ← served as-is, NOT optimized

If an image needs to be a specific filename at a specific URL (favicon, OG image), put it in public/. Otherwise, put it in src/ and import it.

Remote Images

For images at known remote URLs:

<Image src="https://cdn.example.com/hero.jpg" alt="" width={1200} height={600} />

Remote images need explicit width and height (Astro can’t read them at build).

Allow specific domains in astro.config.mjs:

image: {
  domains: ["cdn.example.com"],
}

<Picture> — Multiple Formats

Need format negotiation (AVIF / WebP / JPG)? Use <Picture>:

---
import { Picture } from "astro:assets";
import hero from "../assets/hero.jpg";
---

<Picture
  src={hero}
  alt="Mountains"
  formats={["avif", "webp", "jpg"]}
  widths={[400, 800, 1200]}
/>

Generates a <picture> with multiple <source> elements. Browsers pick the best format and size they support.

Performance Wins

• Smaller files (next-gen formats)
• Explicit dimensions = no CLS
• loading="lazy" by default for <Image> below the fold
• Per-page optimized images, not one giant download

Up Next

Smooth page-to-page transitions.