Skip to main content
The Image component is a primitive for rendering responsive images with theme-aware styling.

​
Import

import { Image } from 'theme-ui'

​
Usage

<Image src="/photo.jpg" alt="Description" />

​
Props

​
src
string
required
Image source URL.
<Image src="/images/photo.jpg" alt="Photo" />
​
alt
string
required
Alternative text for accessibility.
<Image src="/logo.png" alt="Company Logo" />
​
variant
string
Image variant from theme.images.
<Image src="/avatar.jpg" alt="Avatar" variant="avatar" />
<Image src="/hero.jpg" alt="Hero" variant="hero" />
​
sx
ThemeUIStyleObject
Theme-aware styles for custom image appearance.
<Image
  src="/photo.jpg"
  alt="Photo"
  sx={{
    borderRadius: 8,
    boxShadow: 'lg',
  }}
/>
​
width
string | number
Image width.
​
height
string | number
Image height.
​
loading
'lazy' | 'eager'
Browser lazy loading behavior.
<Image src="/below-fold.jpg" alt="Image" loading="lazy" />

​
Inherited Props

Image extends Box and accepts:
  • All standard HTML img attributes
  • Box spacing props (m, p, mx, my, px, py, etc.)

​
Default Styles

The Image component includes these base styles: 
{
  maxWidth: '100%',
  height: 'auto',
}
This ensures images are responsive by default and don’t overflow their containers.

​
Examples

​
Basic Image

<Image src="/photo.jpg" alt="Photo description" />

​
Rounded Image

<Image
  src="/avatar.jpg"
  alt="User avatar"
  sx={{
    borderRadius: '50%',
    width: 64,
    height: 64,
  }}
/>

​
Image with Shadow

<Image
  src="/card-image.jpg"
  alt="Card"
  sx={{
    borderRadius: 4,
    boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)',
  }}
/>

​
Responsive Image Sizes

<Image
  src="/hero.jpg"
  alt="Hero image"
  sx={{
    width: ['100%', '80%', '60%'],
    mx: 'auto',
  }}
/>

​
Image with Border

<Image
  src="/profile.jpg"
  alt="Profile"
  sx={{
    border: '3px solid',
    borderColor: 'primary',
  }}
/>

​
Fixed Size Image

<Image
  src="/thumbnail.jpg"
  alt="Thumbnail"
  width={200}
  height={200}
  sx={{ objectFit: 'cover' }}
/>

​
Lazy Loaded Image

<Image
  src="/large-image.jpg"
  alt="Large image"
  loading="lazy"
/>

​
Image with Overlay

<Box sx={{ position: 'relative' }}>
  <Image src="/bg.jpg" alt="Background" />
  <Box
    sx={{
      position: 'absolute',
      top: 0,
      left: 0,
      right: 0,
      bottom: 0,
      bg: 'rgba(0, 0, 0, 0.4)',
    }}
  />
</Box>

Build docs developers (and LLMs) love

Get started for freeTalk to us