How to Add Images to an Astro Site

Astro can take a big image and turn it into a small, modern one. It does this while your site builds. A build is making the finished copy of your site. In our test, a 62 kB PNG became a 5 kB WebP file. Nothing looked different. WebP is a modern picture format. Here is how to use it.

Step 1: Add your image to the project

Make a folder called src/images. Put your picture in it. For this guide, we will call it team-photo.png.

Keep images inside src when you can. Files in public are copied just as they are. Astro does not shrink them.

Step 2: Use the Image component

Open the page where you want the picture. Add two imports and one tag. A component is a reusable piece of a page:

---
import { Image } from 'astro:assets';
import teamPhoto from '../images/team-photo.png';
---
<Image src={teamPhoto} alt="Our team standing outside the office." width={600} />

The alt text is required. Screen readers read it out loud. It also helps search engines understand the picture.

The image is imported from src. So Astro knows its real size. The width tells Astro how large to make the small version.

Step 3: Build and look at the result

Run npm run build. In the output you will see a line like this:

▶ /_astro/team-photo.CroshMPU_Z1Oj0fM.webp (before: 62kB, after: 5kB)

Astro turned the image into WebP. It resized it. And it gave it a unique file name. That lets browsers cache it safely. A cache is the browser’s saved copy. The HTML it makes also includes loading="lazy". So images lower down the page do not load until needed.

Images in Markdown

Markdown is a simple way to write pages as plain text. In a blog post written in Markdown, use the normal image syntax. Point it at the file with a relative path:

![A starry night sky.](../../images/stars.png)

Images used this way from src are shrunk too. The Image component is not available in .md files. It works only in .astro and .mdx files. MDX is Markdown that can also hold components.

Pictures in several formats

AVIF is a newer picture format. To serve AVIF where the browser supports it, with a backup, use the Picture component:

---
import { Picture } from 'astro:assets';
import teamPhoto from '../images/team-photo.png';
---
<Picture src={teamPhoto} formats={['avif', 'webp']} alt="Our team standing outside the office." />

Images from other websites

Astro only shrinks remote images from sites you approve. Remote means on another website. Add them to astro.config.mjs, your site’s settings file:

export default defineConfig({
  image: {
    domains: ['example.com'],
  },
});

Remote images also need a width and height. Astro cannot read their size ahead of time.

Frequently asked questions

Should images go in src or public?

Put them in src when you can, so Astro can shrink them. Use public only for files that must keep their exact name and bytes, like a favicon.

Why does Astro want alt text?

The alt text describes the image for people who can't see it, and for search engines. Astro's Image component requires it. For an image that is only decoration, use alt="".

Can I use images from another website?

Yes. Give the full address as the src. Astro only shrinks remote images from sites you list in your config. It also needs a width and height for them.