Image

Responsive image with lazy loading, async decoding, and an error fallback. Reserve layout space with native dimensions, wrapper sizing, or `AspectRatio`.

Examples

Default

<Image
  alt="Mountain landscape at sunset"
  height={800}
  src={landscapeSource}
  style={{maxWidth: 720}}
  width={1200}
/>

Responsive Sources

<Image
  alt="Mountain landscape at sunset"
  height={800}
  src={landscapeSource}
  style={{maxWidth: 720}}
  width={1200}
  sizes="(max-width: 640px) 100vw, 720px"
  srcSet="https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=480&auto=format&fit=crop 480w, https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=960&auto=format&fit=crop 960w, https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1440&auto=format&fit=crop 1440w"
/>

Object Fit

cover

contain

<div
  style={{
    display: 'grid',
    gap: 16,
    gridTemplateColumns: 'repeat(2, minmax(0, 1fr))',
    maxWidth: 720,
  }}>
  <div>
    <p>cover</p>
    <AspectRatio ratio={1}>
      <Image alt="Landscape cropped to cover" src={landscapeSource} />
    </AspectRatio>
  </div>
  <div>
    <p>contain</p>
    <AspectRatio ratio={1}>
      <Image
        alt="Full landscape contained in frame"
        objectFit="contain"
        src={landscapeSource}
      />
    </AspectRatio>
  </div>
</div>

Custom Fallback

<Image
  alt="Unavailable product photo"
  height={400}
  src="/missing-image.jpg"
  style={{height: 240, width: 360}}
  width={600}
  fallback={<span>Product image unavailable</span>}
/>

With Aspect Ratio

<div style={{maxWidth: 960}}>
  <AspectRatio ratio={16 / 9}>
    <Image
      alt="Mountain landscape hero"
      fetchPriority="high"
      loading="eager"
      src={landscapeSource}
    />
  </AspectRatio>
</div>

API

Image

Responsive image with lazy loading, async decoding, and an error fallback. Reserve layout space with native dimensions, wrapper sizing, or `AspectRatio`.

Prop	Type	Default	Description
alt*	string	—	Alternative text describing the image. Use an empty string for a decorative image.
className	string	—	Additional CSS class names applied to the wrapper.
data-testid	string	—	Test ID applied to the wrapper.
decoding	ComponentPropsWithoutRef<'img'>['decoding']	'async'	Browser decoding hint.
fallback	ReactNode	—	Content displayed if the image fails to load. Defaults to a muted image placeholder.
loading	ComponentPropsWithoutRef<'img'>['loading']	'lazy'	Browser loading strategy.
objectFit	"fill" | "none" | "contain" | "cover" | "scale-down"	'cover'	How the image is resized within its frame.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the stable wrapper element.
sizes	string	—	Responsive source-size hints.
src*	string	—	Image source.
srcSet	string	—	Responsive image sources.
style	CSSProperties	—	Inline styles applied to the wrapper.