All components (204)

Thumbnail

Surfaces · Thumbnail

What it is and when to use it

An image slot with a fixed shape: the photo of a product in a list, the attachment of a message. It reserves the space from the start (the shape is set by aspect-ratio), so the page does not jump when photos arrive. If the image fails or there is none, the fallback remains: never a broken icon.

When to use it

Small photos in lists, cart lines, attachments, search results.
ratio fixes the shape (1:1, 4:3, 3:4 or 16:9) and width the size (4rem by default).
fit="contain" leaves the whole image, with borders, instead of cropping it to fill.
fallback for what is drawn without a photo; by default, an icon.
rounded makes it fully round.

When not to

The photo of a person: Avatar, which falls back to initials.
The photos of a product to view at large size: Gallery or Carousel.
Comparing two photos, before and after: ImageCompare.

Keyboard: by default it is not focusable. With onPress it is a button (Tab reaches it, Enter and Space press it) named by pressLabel; if instead it has to lead somewhere, the link goes around it.

Accessibility: alt is required: it says what is seen in the image. Empty (alt="") when the thumbnail is decoration and the text next to it already says everything. Without a photo, the fallback takes the alt (role="img"), or is hidden if the alt is empty. Loading is lazy (loading="lazy") except with lazy={false}, for what is seen as soon as the page opens.

Fine-tuning: no variables of its own: it is adjusted with the classes amset-thumbnail, amset-thumbnail--<ratio> (--1-1, --16-9…), amset-thumbnail--cover/--contain and amset-thumbnail--rounded.

What it looks like

Aurelia silver ring with a cubic zirconia

Aurelia ring · Size 14 · €49.90

<Thumbnail src={foto} alt="Aurelia silver ring with a cubic zirconia" width="6rem" />
<Thumbnail alt="Luna pendant, no photo yet" width="6rem" />
<Thumbnail src={cartel} alt="Fall collection poster" ratio="16:9" fit="contain" width="12rem" />

Props

Import it with import { Thumbnail } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`alt`required	`string`	What is seen in the image. Deliberately empty (`alt=""`) when the thumbnail is decoration and the text beside it already says it all.
`caption`	`string`	A short text over the bottom edge: the file name in a gallery.
`className`	`string`	Merged with the library classes; it does not replace them.
`error`	`boolean`	Failed to fetch it: the warning icon instead of the image or the fallback.
`fallback`	`ReactNode`	What is drawn if there is no image or if it fails to load.
`fit`	`ThumbnailFit`	`cover` crops to fill; `contain` leaves the whole image with borders.
`lazy`	`boolean`	Lazy loading. On by default: a list of 200 photos is not loaded in full.
`loading`	`boolean`	The image is arriving: a skeleton with shine in its place, without jumps.
`onPress`	`() => void`	With this the thumbnail can be pressed: a transparent button on top, named by `pressLabel` (or `alt`), that opens the viewer, the zoom or whatever fits. It asks for 44 px tall on a touch screen.
`pressLabel`	`string`	The name of the `onPress` button: "View report.png". By default, `alt`.
`ratio`	`ThumbnailRatio`	—
`rounded`	`boolean`	—
`src`	`string`	—
`width`	`string`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: