Image

A constrained image container with defined aspect ratios, corner radius options, and loading behaviour.

Figma

Component specification in the CDS Foundation file.

When to use

Use the image component to display a visual asset in a defined, constrained container. It works well for:

Product images, recipe photos, or editorial photography inside a card or page section.
Hero banners and promotional tiles where the image fills a specific aspect ratio.
Thumbnails in list or grid layouts.

When not to use

Don't use this component for decorative background patterns — handle those in CSS.
Avoid using it for icons or illustrations that need to scale freely; use an icon or an SVG element instead.
Don't use it when the image dimensions are not meaningful (e.g., a logo in a header) — an inline <img> element is more appropriate.

The image fills its container while maintaining the selected aspect ratio. The image is cropped with object-fit: cover if the source proportions don't match the container ratio. No interactive states exist unless the image is wrapped in an interactive element (such as a card or link).

When the image has not yet loaded, the container shows a placeholder background. If the image fails to load, the container falls back to the same placeholder.

Anatomy

Container — defines the aspect ratio and applies the corner radius. The container clips the image content.
Image — the actual media asset, scaled and cropped to fill the container.
Placeholder — shown while the image is loading or if it fails to load. Maintains the container dimensions.

Variants

Aspect ratio

Ratio	Use case
1	Avatars, product thumbnails, square cards.
4	Standard photography, recipe images, editorial tiles.
16	Video thumbnails, wide hero images, landscape banners.
21	Ultra-wide hero banners and cinematic crops.

Orientation

Horizontal — the long edge runs left to right. Use for standard landscape images.
Vertical — the long edge runs top to bottom. Use for portrait images or tall format cards.

Radius

None — square corners.
xSmall — a minimal, subtle rounding.
Small — light rounding; suits most contexts.
Medium — moderate rounding; matches the default card radius.
Large — prominent rounding; use for expressive or hero contexts.

States

Default — image is loaded and visible.
Loading — image has not yet loaded; placeholder background is shown.
Error — image failed to load; placeholder background is shown.

Placement & layout

The image component spans the full width of its parent container. It does not add external margin — spacing is controlled by the parent layout or the containing card.

In a grid, all image containers in the same row should use the same aspect ratio and radius to maintain visual alignment.

Accessibility

Every image must have an alt attribute. For informative images, the alt text should describe the content and purpose of the image concisely. For decorative images, use alt="" so screen readers skip it.

Do not include information in the image that is not also available in the surrounding text, unless the image itself is the main content.

Card — the most common parent for image components.
Icon Badge — for small, decorative icon containers, not photographic content.