CSS aspect-ratio sizing

What aspect-ratio does

The CSS aspect-ratio property sets a preferred width-to-height ratio for a box. Combined with one definite dimension, the box sizes the other dimension from the ratio. The flagship use is media: an image or video that has not loaded yet gets the space it will occupy, instead of the page reflowing when it arrives. This is a direct fix for the layout shift that images cause, alongside the image aspect ratio article's HTML-side approach.

.media {
  width: 100%;
  aspect-ratio: 16 / 9;
}

With width: 100% the box computes height from the ratio. Without a definite width, the box uses its natural width; with aspect-ratio: auto, the preferred ratio falls back to the replaced element's intrinsic ratio (an actual image with width="400" height="300" has an intrinsic ratio of 4/3).

The interaction with auto and intrinsic ratios

The exact resolution rule (per the CSS sizing spec) is what trips people up:

• The property is an addition to the box's preferred size, not a replacement. A box that already has an intrinsic ratio (a loaded <img>) keeps using that intrinsic ratio unless something forces a different one.
• On a replaced element whose intrinsic dimensions are unknown while loading (a video that streams nothing, an image whose width/height attributes are absent), aspect-ratio: 16/9 is what reserves the space.
• aspect-ratio: auto is the value that tells browsers to use the intrinsic ratio when there is one, and fall back to the ratio for boxes without one. The default for replaced elements is effectively auto; for a plain <div> it is auto (no ratio at all).

The practical consequences for layout:

img.hero {
  width: 100%;
  aspect-ratio: 16 / 9;   /* reserves space before the image arrives */
  object-fit: cover;      /* crops overflow instead of distorting */
}

The object-fit article covers the crop side; ratio plus object-fit is the pair that stops both the shift and the squish.

Where it removes layout shift

The two classic shifts: images without width/height attributes on an article body, and embeds (YouTube, maps) where the iframe occupies zero space until it loads. For both:

.video-wrap {
  aspect-ratio: 16 / 9;
}

An empty wrapper with a definite ratio and a loaded iframe keeps the page height stable. Fonts load late and change height too; that is covered by font loading and the CLS guide tracks the measured impact.

Gotchas

• Ratio needs one definite preferred size. aspect-ratio alone with width and height both auto: the box sizes to the intrinsic value and the ratio does nothing. Give the box width: 100% (or a fixed size) first.
• An intrinsic size beats the declared ratio. An element with its own intrinsic ratio (a loaded image) keeps that ratio; aspect-ratio: 2 / 1 on a <div> holding a 4:3 <img> makes the box 2:1 but the image still renders at its intrinsic 4:3, cropped by object-fit only if you want that.
• Do not use it on content that shrinks the text. A ratio on a multi-line element that you mean to be fixed reserves exact height and cuts content that grows (a summary paragraph). Reserve aspect-ratio for media and containers whose content is a fixed-ratio child.

The image layout-shift guide is the image-specific companion, and the CSS box model article explains how height and width interact with the box it sizes.