Documentation Index
Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
Use this file to discover all available pages before exploring further.
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" />
Alternative text for the image. Required for accessibility.<Image src={img} alt="A beautiful sunset over the ocean" />
Desired width of the image. Sets the width attribute and resizes the image.<Image src={img} width={300} alt="..." />
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 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 of the image when using fit. Similar to CSS object-position.<Image src={img} fit="cover" position="center" alt="..." />
Background color to use when converting transparent images to non-transparent formats.<Image src={img} background="#ffffff" format="jpg" alt="..." />
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
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="..." />
Format to use for the fallback <img> element.Default: 'png'<Picture src={img} formats={['avif', 'webp']} fallbackFormat="jpg" alt="..." />
Attributes to apply to the <picture> element.<Picture
src={img}
pictureAttributes={{ class: 'picture-wrapper' }}
alt="..."
/>
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>
Image transformation options.src
ImageMetadata | string
required
Image source.
Object containing optimized image data.URL of the optimized image.
Srcset data for responsive images.Formatted srcset attribute string.
HTML attributes for the image (width, height, etc.).
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} />
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' }],
},
});
<Image
src="https://example.com/image.jpg"
width={800}
height={600}
alt="Remote image"
/>