Astro Image and Picture Props Cheatsheet

This cheatsheet lists all the Astro image props for <Image />, <Picture /> and getImage() from astro:assets, plus the image options in astro.config.mjs. Use it to look up the right prop quickly; for when and why, see responsive images in Astro and the Astro performance guide.

Key Takeaways

• Local images: import them and pass the import as src. Remote images: pass a URL plus width and height (or inferSize).
• alt is required. Use alt="" for decorative images.
• layout generates srcset and sizes for you; priority is for the one LCP image.
• widths and densities can’t be used together.

Imports

---
import { Image, Picture, getImage } from 'astro:assets';
import hero from '../assets/hero.jpg';
---

Image props

Prop	Type	Notes
src	import, URL string	Required. Strings to local files fail; import them
alt	string	Required. "" for decorative
width, height	number	Required for remote images unless inferSize
inferSize	boolean	Fetch remote dimensions at build time
layout	'constrained', 'full-width', 'fixed', 'none'	Generates srcset/sizes
widths	number[]	Explicit srcset widths; pair with sizes
sizes	string	Tells the browser the rendered width
densities	(number or '2x')[]	1x/2x srcset; not with widths or layout
format	'webp', 'avif', 'png', 'jpg', 'svg'	Default webp
quality	number or 'low', 'mid', 'high', 'max'	Encoder quality
fit	'cover', 'contain', 'fill', 'none', 'scale-down'	How the image fills its box when cropped
position	string	Focal point for fit, e.g. 'top'
priority	boolean	Eager load, high fetch priority; LCP image only
loading, decoding	HTML values	Defaults: lazy, async

Any other attribute (class, style, id, data-*) passes through to the <img>.

Picture extras

Prop	Notes
formats	e.g. ['avif', 'webp'], one <source> each
fallbackFormat	Format for the final <img>
pictureAttributes	Attributes for the <picture> element

<Picture src={hero} alt="Studio" formats={['avif', 'webp']} layout="full-width" />

Layout values

layout	srcset	sizes
constrained	Widths up to 2× width (capped at original)	(min-width: Wpx) Wpx, 100vw
full-width	Breakpoint widths up to the original	100vw
fixed	1× and 2× width	Wpx
none	None	None

Common recipes

<!-- Hero (LCP) -->
<Image src={hero} alt="Product dashboard" layout="full-width" priority />

<!-- Card in a 3-column grid -->
<Image src={thumb} alt="" widths={[320, 480, 640]} sizes="(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw" />

<!-- Avatar -->
<Image src={avatar} alt="Anika Rao" width={64} height={64} densities={[1, 2]} />

<!-- Remote CMS image -->
<Image src={post.coverUrl} alt={post.coverAlt} width={1200} height={630} />

getImage()

const og = await getImage({ src: hero, width: 1200, height: 630, format: 'jpg' });
og.src;          // URL of the processed file
og.srcSet;       // srcset values, when widths/densities are set
og.attributes;   // width, height, loading, decoding...

Server only; see getImage() must be used on the server.

Config

image: {
  layout: 'constrained',
  responsiveStyles: true,
  domains: ['images.example.com'],
  remotePatterns: [{ protocol: 'https', hostname: '**.cdn.example.com' }],
  service: passthroughImageService(),   // skip processing (import from 'astro/config')
},

Content collections

schema: ({ image }) => z.object({ cover: image(), coverAlt: z.string() }),

Errors you’ll meet

Message	Fix
Image missing required “alt”	Add alt
Missing image dimensions	Add width/height or inferSize
Remote image is not allowed	Allow the domain
Cannot set both densities and widths	Pick one
Could not find Sharp	Install sharp

Every prop is documented in the astro:assets reference.

FAQ

What format does Astro’s Image component output by default?

WebP, unless you set format.

Are images in public/ optimised?

No. Only imported images (and allowed remote ones) are processed.