Skip to main content
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"
/>

Build docs developers (and LLMs) love

Get started for freeTalk to us