Thumbnail

A framed, fixed-ratio image with a neutral background and a graceful fallback for missing or broken sources.

Usage

import { Thumbnail } from '@epilot/spark-ui/thumbnail'

function DocumentThumbnail() {
  return <Thumbnail alt="Installation report cover page" src={reportCoverUrl} />
}

Use Thumbnail for a photo or user-generated image that needs a fixed frame and a predictable fallback (a device photo, a document cover, an uploaded attachment). For a symbolic glyph instead of a real image, use Icon. For a placeholder while content is still loading, use Skeleton.

Examples

Ratios

ratio sets the frame's aspect ratio; the image (or fallback) fills it.

1:1

3:2

4:3

16:9

3:4

2:3

Fit

fit="cover" scales the image to fill the frame and crops the overflow. fit="contain" scales it to fit inside the frame, letterboxing against the neutral background, visible when the image doesn't share the frame's aspect ratio, or has a transparent background of its own.

cover

contain

contain, transparent

Radius

radius rounds the frame's corners, from none to full.

none

full

Fallback

children renders centered in place of the image whenever there's no src, or the image fails to load. A new src clears a previous load error, so retrying a fixed URL doesn't get stuck on the fallback.

no src

broken src

API Reference

Prop	Type	Default	Description
`src`	`string`	—	Image URL. Omit it, or let it fail to load, to show `children` instead.
`alt`	`string`	`''`	Alt text for the image. The default is decorative; pass real text for a meaningful image.
`ratio`	`'1:1' \| '3:2' \| '4:3' \| '16:9' \| '3:4' \| '2:3'`	`'1:1'`	Aspect ratio of the frame.
`fit`	`'cover' \| 'contain'`	`'cover'`	How the image fills the frame: crop to fill, or letterbox to fit.
`radius`	`'none' \| 'sm' \| 'md' \| 'lg' \| 'full'`	`'md'`	Corner rounding of the frame.
`imgProps`	`React.ComponentProps<'img'>`	—	Escape hatch forwarded to the underlying `<img>` (e.g. `loading`, `srcSet`). Its `className` merges with the fit styling; its `onError` runs alongside the fallback logic.
`children`	`React.ReactNode`	—	Fallback content, shown centered instead of the image when there's no `src` or it fails to load.

The component also forwards all other div props (including className, which merges with the base frame styles) and a ref to the outer <div>.

Accessibility

Give a meaningful image a real alt describing what it shows; the default alt="" marks the image as decorative.
The fallback (children) is plain content in the DOM, not an ARIA live region. If it conveys information beyond "no image", give it its own accessible label (e.g. via aria-label on an icon).

Thumbnail

On this page