Skip to main content

Image

The Image component displays external images with support for sizing presets, border radius, shadows, opacity, and aspect ratio control.

Props

PropTypeDefaultDescription
srcstringRequiredSource URL of the image
altstring-Alternative text for accessibility
sizestring | number-Size preset: xs, sm, md, lg, xl, or pixel value
widthstring | number-Specific width
heightstring | number-Specific height
radiusstring | number"md"Border radius: none, sm, md, lg, xl, full, or number
fitstring"cover"Object fit mode: cover, contain, fill
backgroundstring-Background color while loading
flushbooleanfalseRemoves border radius (useful in cards)
borderWidthnumber-Border width in pixels
borderColorstring-Border color
shadowstring"none"Shadow depth: none, sm, md, lg
opacitynumber1Opacity (0-1)
aspectRationumber-Aspect ratio (e.g., 16/9, 1, 4/3)

Size Presets

  • "xs" - 32px
  • "sm" - 48px
  • "md" - 64px
  • "lg" - 96px
  • "xl" - 128px

Examples

Basic Image

<Image src="https://example.com/photo.jpg" alt="Description" />

With Size Preset

<Image src="https://example.com/photo.jpg" size="lg" />

Avatar (Circular)

<Image
  src="https://example.com/avatar.jpg"
  size="md"
  radius="full"
/>

Card Banner

<Image
  src="https://example.com/banner.jpg"
  height={200}
  width="100%"
  flush
/>

With Shadow

<Image
  src="https://example.com/photo.jpg"
  size="xl"
  shadow="md"
  radius="lg"
/>

With Border

<Image
  src="https://example.com/photo.jpg"
  size="lg"
  borderWidth={2}
  borderColor="#8B5CF6"
  radius="lg"
/>

Aspect Ratio

{/* 16:9 aspect ratio */}
<Image
  src="https://example.com/video-thumb.jpg"
  width="100%"
  aspectRatio={16/9}
/>

{/* Square */}
<Image
  src="https://example.com/photo.jpg"
  width="100%"
  aspectRatio={1}
/>

Opacity Overlay Effect

<Image
  src="https://example.com/background.jpg"
  width="100%"
  height={200}
  opacity={0.5}
/>

Contain vs Cover

<Row gap="md">
  {/* Cover (default) - fills container, may crop */}
  <Image src="..." size="lg" fit="cover" />

  {/* Contain - shows full image, may letterbox */}
  <Image src="..." size="lg" fit="contain" />
</Row>

Common Patterns

User Profile Card

<Card>
  <Row gap="md" align="center">
    <Image
      src={user.avatar}
      size="lg"
      radius="full"
    />
    <Col gap="xs">
      <Title value={user.name} size="sm" />
      <Text value={user.email} color="muted" size="sm" />
    </Col>
  </Row>
</Card>

Product Card

<Card padding="none">
  <Image
    src={product.image}
    width="100%"
    aspectRatio={4/3}
    flush
  />
  <Col padding="md" gap="xs">
    <Title value={product.name} size="sm" />
    <Text value={`$${product.price}`} weight="bold" />
  </Col>
</Card>
<Row gap="sm" wrap>
  {images.map(img => (
    <Image
      key={img.id}
      src={img.url}
      size="lg"
      radius="md"
    />
  ))}
</Row>

Hero Banner

<Box width="100%">
  <Image
    src="https://example.com/hero.jpg"
    width="100%"
    height={300}
    radius="lg"
    shadow="lg"
  />
</Box>

Thumbnail with Hover Effect

<Image
  src="https://example.com/thumbnail.jpg"
  size="md"
  radius="md"
  shadow="sm"
  borderWidth={1}
  borderColor="rgba(0,0,0,0.1)"
/>