Image

A styled-system <img> primitive. Accepts all layout, space, background, and position props from the theme, plus objectFit / objectPosition for common image sizing patterns and borderRadius for rounded corners.

Built-in source priority and error recovery: when a source fails to load the component advances to the next URL automatically. onError fires only when all sources are exhausted.

Source priority

Initial render - props map to <img> attributes as follows:

src → src attribute.
srcSet → srcset attribute (used alongside src, or as the primary source when src is absent).
fallback → src attribute when both src and srcSet are absent.

Error recovery - when the browser fails to load, the component advances through phases:

src + srcSet  →  src (srcSet dropped)  →  fallback  →  onError
src only      →  fallback              →  onError
srcSet only   →  fallback              →  onError

onError fires only after all sources are exhausted.

Examples

Default

<Image
  src="/soroush.svg"
  alt="Soroush logo"
  width="200px"
  height="200px"
  objectFit="contain"
/>

Cover

<Image
  src="/soroush.svg"
  alt="Cover"
  width="300px"
  height="200px"
  objectFit="cover"
/>

With Fallback

<Image
  src="broken.jpg"
  alt="With fallback"
  fallback="/soroush.svg"
  width="200px"
  height="200px"
  objectFit="contain"
/>

Object Fit Variants

cover

contain

fill

none

scale-down

<div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
  {objectFitTokens.map((fit) => (
    <div key={fit} style={{ textAlign: 'center' }}>
      <Image src={DEMO_IMG} alt={fit} width="150px" height="120px" objectFit={fit} />
      <p style={{ fontSize: '12px', margin: '4px 0 0' }}>{fit}</p>
    </div>
  ))}
</div>

Image API reference