Image

Image with aspect ratios and thumbhash placeholders

Installation

pnpm add @wandercom/design-system-web

Usage

7 lines
import { Image } from '@wandercom/design-system-web/ui/image';

export function Example() {
  return (
    <Image src="https://images.unsplash.com/photo-123" alt="Description" />
  );
}

Thumbhash placeholder

Progressive loading with blurred placeholders:

5 lines
<Image
  src="https://images.unsplash.com/photo-123"
  alt="Description"
  thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
/>

Placeholder fades out when image loads.

Preview

Square

Loading example...
4 lines
<Image
  aspectRatio="square"
  src="https://images.unsplash.com/photo-1613914049786-b7e3e8323348?w=600&dpr=2&q=80"
/>

Portrait

Loading example...
4 lines
<Image
  aspectRatio="portrait"
  src="https://images.unsplash.com/photo-1613914049786-b7e3e8323348?w=600&dpr=2&q=80"
/>

Landscape

Loading example...
4 lines
<Image
  aspectRatio="landscape"
  src="https://images.unsplash.com/photo-1613914049786-b7e3e8323348?w=600&dpr=2&q=80"
/>

Rounded Large

Loading example...
4 lines
<Image
  rounded="lg"
  src="https://images.unsplash.com/photo-1613914049786-b7e3e8323348?w=600&dpr=2&q=80"
/>

Rounded Extra Large

Loading example...
4 lines
<Image
  rounded="xl"
  src="https://images.unsplash.com/photo-1613914049786-b7e3e8323348?w=600&dpr=2&q=80"
/>

Props

aspectRatio

'square' | 'portrait' | 'landscape'
Aspect ratio constraint. 'square' (1:1), 'portrait' (3:4), 'landscape' (4:3).

rounded

'none' | 'lg' | 'xl'
border border-secondary radius. 'none' (0px), 'lg' (8px), 'xl' (12px). Defaults to 'lg'.

thumbhash

string
Thumbhash string for blurred placeholder while image loads.

asChild

boolean
Renders children and merges props.

className

string
Additional CSS classes applied to the wrapper `<div>` (controls aspect ratio, rounding, and box size).

imgClassName

string
Additional CSS classes applied to the inner `<img>` element.

wrapperStyle

CSSProperties
Inline styles applied to the wrapper. Use to size the box without affecting the inner `<img>`.

wrapperWidth

CSSProperties["width"]
Convenience shorthand for `wrapperStyle.width`.

wrapperHeight

CSSProperties["height"]
Convenience shorthand for `wrapperStyle.height`.

loadingAlt

string
Alt text for the decorative blur placeholder (aria-hidden). Defaults to "Loading image".

width / height

number | string
Forwarded to the inner `<img>` as standard HTML attributes (does not size the wrapper — use `wrapperWidth` / `wrapperHeight` for that).

style

CSSProperties
Forwarded to the inner `<img>` (use for `objectFit`, `objectPosition`, etc.).
Image