Aspect ratio

Default density Compact density Restart from the initial state Show the copyable source

Usage

Set ratio to width divided by height, such as 1.7778 for 16:9 or 1 for a square. The box takes its width from the container and derives its height, so content can’t stretch it. Always pass a ratio; the 16:9 default exists only for compatibility.

Invalid property assignments throw RangeError and preserve the previous valid ratio. Invalid attribute values also report the validation error instead of silently clamping geometry.

Ratios

Default density Compact density Restart from the initial state Show the copyable source

21:9

1:1

9:16

Reserving the box before media loads prevents layout shift in feeds, galleries and video embeds. Width comes from the surrounding layout; the ratio is the only size input.

Container width

Default density Compact density Restart from the initial state Show the copyable source

The same 16:9 box keeps its shape in a sidebar, a card and a feature slot. Give it a width, or let the container shrink it, and the height follows.

Fit

Default density Compact density Restart from the initial state Show the copyable source

fit sets how images and video fill the box, like object-fit: cover crops, contain letterboxes and fill stretches. It never changes the ratio. The box adds no image semantics, so keep alt on the image itself.

API Reference

Every element also accepts motion-policy.

Related

Components, widgets and patterns that use this one.