XDS — Design System

Thumbnail@xds/core v0.0.14 · XDSThumbnail

Usage

Thumbnail displays a compact, square preview of an image attachment. It shows a shimmer effect while uploading, the image on success, and a placeholder icon when no source is set. Use it in chat composers, file upload lists, or anywhere you need a small image preview with optional remove and click actions.

ts
import {XDSThumbnail} from '@xds/core/Thumbnail'

Best practices

Guidance	Practices
Do	Always provide a label prop with the file name so the thumbnail and its remove button are accessible to screen readers and show a tooltip on hover.
Do	Use isLoading without a src to show a skeleton during initial upload, and isLoading with a src to show a spinner overlay once a preview URL is available.
Do	Pair onClick with a lightbox or detail view so users can inspect the full image — the thumbnail adds button semantics and a hover shadow automatically.
Don't	Don't use Thumbnail for non-image file types like PDFs or spreadsheets — use a file attachment component with an appropriate icon instead.
Don't	Don't omit alt text when a src is provided — screen readers need a description of the image content, not just the file name from label.

Examples

Common configurations, variations, and states.

Thumbnail — Disabled

Thumbnails in the disabled state with reduced opacity. The remove button and click handler are suppressed when disabled.

Thumbnail — Gallery

A row of clickable thumbnails with labels that open a detail view. Use for image attachment lists where users need to preview and manage uploads.

Thumbnail — Removable

Thumbnails with a remove button overlay. The close button uses APCA luminance detection to stay visible on both dark and light images.

Thumbnail — States

All visual states side by side: image loaded, placeholder, skeleton loading, and upload overlay. Demonstrates the full lifecycle of a thumbnail from empty to loaded.

Usage

import {XDSThumbnail} from '@xds/core/Thumbnail'

Best practices

Guidance	Practices
Do	Always provide a label prop with the file name so the thumbnail and its remove button are accessible to screen readers and show a tooltip on hover.
Do	Use isLoading without a src to show a skeleton during initial upload, and isLoading with a src to show a spinner overlay once a preview URL is available.
Do	Pair onClick with a lightbox or detail view so users can inspect the full image — the thumbnail adds button semantics and a hover shadow automatically.
Don't	Don't use Thumbnail for non-image file types like PDFs or spreadsheets — use a file attachment component with an appropriate icon instead.
Don't	Don't omit alt text when a src is provided — screen readers need a description of the image content, not just the file name from label.