Assets API

API reference for Astro’s built-in image optimization and asset handling

Astro provides built-in image optimization and asset handling through the astro:assets module.

Importing

import { Image, Picture, getImage } from 'astro:assets';

Image Component

The <Image /> component optimizes images and generates responsive image markup.

import { Image } from 'astro:assets';
import myImage from '../assets/my-image.png';

<Image src={myImage} alt="A description of my image" />

Props

src · ImageMetadata | string · required

Image source. Can be an imported image or a URL string.

import localImage from '../images/photo.jpg';

<Image src={localImage} alt="Local image" />
<Image src="/public-image.jpg" alt="Public image" />
<Image src="https://example.com/remote.jpg" alt="Remote image" />

alt · string · required

Alternative text for the image. Required for accessibility.

<Image src={img} alt="A beautiful sunset over the ocean" />

width · number | string

Desired width of the image. Sets the width attribute and resizes the image.

<Image src={img} width={300} alt="..." />

height · number | string

Desired height of the image. Sets the height attribute and resizes the image if width is not provided.

<Image src={img} height={200} alt="..." />

format · 'avif' | 'webp' | 'png' | 'jpg' | 'jpeg' | 'svg' | string

Output format for the image.

Default: 'webp'

<Image src={img} format="avif" alt="..." />

quality · 'low' | 'mid' | 'high' | 'max' | number

Quality preset or numeric value (0-100) for the output image.

<Image src={img} quality="high" alt="..." />
<Image src={img} quality={85} alt="..." />

densities · (number | `${number}x`)[]

Pixel densities to generate for the image srcset.

<Image src={img} densities={[1, 2, 3]} alt="..." />
<Image src={img} densities={['1x', '2x']} alt="..." />

widths · number[]

Widths to generate for the image srcset.

<Image src={img} widths={[400, 800, 1200]} alt="..." />

fit · 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | string

How the image should be resized to fit the dimensions.

Default: 'cover'

<Image src={img} width={300} height={200} fit="contain" alt="..." />

position · string

Position of the image when using fit. Similar to CSS object-position.

<Image src={img} fit="cover" position="center" alt="..." />

background · string

Background color to use when converting transparent images to non-transparent formats.

<Image src={img} background="#ffffff" format="jpg" alt="..." />

inferSize · boolean

Automatically infer width and height from the source image.

Default: true for local images

<Image src={img} inferSize alt="..." />

HTML Attributes

All standard HTML <img> attributes are also supported:

<Image 
  src={img} 
  alt="Description"
  class="rounded-lg shadow-md"
  loading="lazy"
  decoding="async"
/>

Example

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

<Image 
  src={heroImage}
  width={800}
  height={600}
  format="webp"
  quality="high"
  alt="Hero image showing our product"
  class="hero-image"
/>

Picture Component

The <Picture /> component generates a <picture> element with multiple sources and formats.

import { Picture } from 'astro:assets';
import myImage from '../assets/my-image.png';

<Picture 
  src={myImage} 
  formats={['avif', 'webp']} 
  alt="A description" 
/>

Props

formats · ImageOutputFormat[]

Array of image formats to generate. The component will create a <source> for each format.

Default: ['webp']

<Picture src={img} formats={['avif', 'webp', 'png']} alt="..." />

fallbackFormat · ImageOutputFormat

Format to use for the fallback <img> element.

Default: 'png'

<Picture src={img} formats={['avif', 'webp']} fallbackFormat="jpg" alt="..." />

pictureAttributes · HTMLAttributes

Attributes to apply to the <picture> element.

<Picture 
  src={img} 
  pictureAttributes={{ class: 'picture-wrapper' }}
  alt="..." 
/>

All other props from the Image component are also supported.

Example

---
import { Picture } from 'astro:assets';
import headerImage from '../assets/header.png';
---

<Picture
  src={headerImage}
  formats={['avif', 'webp']}
  widths={[400, 800, 1200]}
  sizes="(max-width: 800px) 100vw, 800px"
  alt="Page header image"
  class="header-image"
/>

getImage

Programmatically get optimized image data without rendering an <img> tag.

getImage(options: ImageTransform): Promise<GetImageResult>

options · ImageTransform · required

Image transformation options.

src · ImageMetadata | string · required

Image source.

width · number

Desired width.

height · number

Desired height.

format · ImageOutputFormat

Output format.

quality · ImageQuality

Image quality.

All other Image component props are also supported.

return · Promise<GetImageResult>

Object containing optimized image data.

src · string

URL of the optimized image.

srcSet · object

Srcset data for responsive images.

values · SrcSetValue[]

Array of srcset values.

attribute · string

Formatted srcset attribute string.

attributes · Record<string, any>

HTML attributes for the image (width, height, etc.).

options · ImageTransform

Processed transformation options.

Example

---
import { getImage } from 'astro:assets';
import myImage from '../assets/my-image.png';

const optimizedImage = await getImage({
  src: myImage,
  width: 800,
  format: 'webp',
  quality: 'high',
});
---

<img src={optimizedImage.src} {...optimizedImage.attributes} alt="..." />

<!-- Use in CSS -->
<style define:vars={{ bgImage: `url(${optimizedImage.src})` }}>
  .hero {
    background-image: var(--bgImage);
  }
</style>

<!-- Generate Open Graph images -->
<meta property="og:image" content={optimizedImage.src} />

ImageMetadata Type

Type for imported images.

type ImageMetadata = {
  src: string;
  width: number;
  height: number;
  format: 'png' | 'jpg' | 'jpeg' | 'tiff' | 'webp' | 'gif' | 'svg' | 'avif';
};

Example

---
import type { ImageMetadata } from 'astro';
import logo from '../assets/logo.png';

const image: ImageMetadata = logo;
console.log(image.width); // 800
console.log(image.height); // 600
console.log(image.format); // 'png'
---

Remote Images

To use remote images, configure image.domains or image.remotePatterns in your Astro config:

// astro.config.mjs
export default defineConfig({
  image: {
    domains: ['example.com'],
    remotePatterns: [{ protocol: 'https' }],
  },
});

Then use remote URLs with the Image component:

<Image 
  src="https://example.com/image.jpg"
  width={800}
  height={600}
  alt="Remote image"
/>