React Image component

Preview

<Image
  src="https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=400&h=300&fit=crop"
  alt="Code on a screen"
  width={300}
/>

Usage

Use when

Product shots, thumbnails, and hero art
Uploads you do not control and cannot trust to load

Avoid when

A person (use Avatar)
A symbol (use Icon)
Pure decoration behind content (use a CSS background)

Implementation notes

Set aspectRatio so a grid holds its shape before the file arrives
objectFit="contain" for graphics, "cover" for photography
Leave radius at none inside a card or frame that already clips its corner
The built-in fallback prints the alt words; pass fallback only to say something more useful
imgProps, onImageLoad, and onImageError expose the raw img when you need it

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

Aspect Ratios

Lock the frame so a grid stays even whatever the file is.

<div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
  <Image
    src="https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=200&fit=crop"
    alt="Square image"
    aspectRatio="1:1"
    width={100}

Corner Roles

none leaves the corner to the container; control, nested and surface are the radius roles.

<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
  <Image
    src="https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=200&fit=crop"
    alt="none corner"
    radius="none"
    width={80}

Broken Source

A dead URL shows the band, a glyph and the alt words, never a broken-image icon.

<Image
  src="https://invalid-url.example/image.jpg"
  alt="Team photo from the offsite"
  aspectRatio="4:3"
  width={240}
  radius="control"

API reference

Component props
Prop	Type	Default	Description
`alt`Required	`string`	Not set	What the image shows; also the words the built-in error fallback prints
`aspectRatio`	`ImageAspectRatio \| undefinedauto1:14:316:9`	`auto`	The frame's aspect ratio
`fallback`	`React.ReactNode`	Not set	Replaces the built-in error fallback (band, glyph and the alt words)
`height`	`string \| number \| undefined`	Not set	Height of the image container
`imgProps`	`Omit<React.ImgHTMLAttributes<HTMLImageElement>, "className" \| "style" \| "onLoad" \| "onError" \| "src" \| "alt" \| "height" \| "width"> \| undefined`	Not set	Additional props for the underlying img element (except src/alt/size/style/events)
`objectFit`	`ImageObjectFit \| undefinedcovercontain`	`cover`	How the image fills the frame: cover crops, contain letterboxes on the band
`onImageError`	`React.ReactEventHandler<HTMLImageElement> \| undefined`	Not set	Called when the underlying img element fails to load
`onImageLoad`	`React.ReactEventHandler<HTMLImageElement> \| undefined`	Not set	Called when the underlying img element loads
`radius`	`ImageRadius \| undefinednonenestedsurfacecontrol`	`none`	Corner role. none leaves the corner to the container that clips it
`src`Required	`string`	Not set	Image source URL
`width`	`string \| number \| undefined`	Not set	Width of the image container
`className`	`string \| undefined`	Not set	Additional class name
`style`	`CSSProperties \| undefined`	Not set	Inline styles

Accessibility

alt is required — describe what the picture shows
Decoration takes alt=""
Words baked into an image must be repeated in alt

CardchildCommon pattern to use Image at top of product cards
AvataralternativeUse Avatar for user profile pictures

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.