CSS aspect-ratio — Glossary

CSS aspect-ratio is a property that gives a box a preferred width-to-height ratio, written as a ratio such as 16 / 9, so the browser can compute one side from the other. It is defined in CSS Box Sizing Module Level 4 and has been available in all browsers since September 2021, per MDN. The initial value is auto, which uses the intrinsic ratio of images and video and gives other boxes no ratio.

How it works

The ratio is width divided by height. aspect-ratio: 16 / 9 means the width is 16 parts for every 9 parts of height, and a plain number such as 1 or 0.5 is also accepted. A ratio only acts when at least one size is auto. If both width and height are set, the ratio has no effect.

Syntax: auto, a ratio, or both, as in auto 4 / 3. With both, a replaced element such as an image uses its own ratio once loaded, and the written ratio before that.
Box model: the ratio applies to the box set by box-sizing. With content-box, padding is added outside the ratio.
Invalid values: a negative number or the colon form 16:9 is rejected.
Not for inline boxes: it applies to all elements except inline boxes and internal table and ruby boxes.

Chromium 153 measured these boxes, all in a 400px wide container unless a width is shown:

#a { aspect-ratio: 16 / 9; }                          /* width auto */
#b { aspect-ratio: 16 / 9; height: 100px; }           /* height set */
#c { aspect-ratio: 1; width: 100px; height: 300px; }  /* both set */
#f { aspect-ratio: 3 / 2; width: 150px; padding: 10px; box-sizing: content-box; }
#g { aspect-ratio: 3 / 2; width: 150px; padding: 10px; box-sizing: border-box; }

a 400 x 225
b 177.765625 x 100
c 100 x 300
f 170 x 120
g 150 x 100

Box a fills the container and derives 225 from 400 x 9 / 16. Box b has a set height, so the width is derived instead and no longer fills the row. In c both sizes are set, so the ratio is ignored. In f the 3 / 2 ratio applies to the 150 by 100 content box, and padding adds 20 to each side.

How do you make a responsive 16:9 video box?

Set aspect-ratio: 16 / 9 and width: 100% on the wrapper, with no height. The wrapper keeps a 16 by 9 shape at any width, replacing the older padding-top: 56.25% hack. For an img, an iframe or a video, also add width and height attributes to the element, so the browser can reserve space before the file loads.

Why does my aspect-ratio box grow taller than expected?

An element with a preferred ratio has an automatic minimum size, so its content can push it past the ratio. In the same run, a 100px wide box with aspect-ratio 1 and sixteen words of text grew taller than 100px (the exact height depends on the font). Adding overflow: hidden made it 100 x 100, because a scroll container gets no content-based minimum. You can also set min-height: 0.

Common pitfalls

Setting both width and height: the ratio is ignored, as box c shows. Leave one size as auto.
Writing 16:9: CSS.supports returned false for the colon form. Use 16 / 9 or 1.7778.
Content overflow stretching the box: the automatic minimum size grows the box. Add overflow hidden or min-height 0 when the shape must be exact.
Expecting padding inside the ratio: with content-box, f measured 170 x 120, not 150 x 100. Use border-box to include padding.
Using it on inline elements: a span with display inline ignores it. Make it inline-block or block first.
Zero or degenerate ratios: a ratio with a 0 term is degenerate and the property behaves as auto.

Related terms

CSS Grid — grid items can take a ratio on their auto-sized axis
Flexbox — flex items respect a ratio when their cross size is auto
CSS min() and max() — cap the size that the ratio then scales from
Viewport units — a common source of the width the ratio derives from
CSS clamp() — bounds a fluid width before the ratio applies