CSS aspect-ratio: Browser Support, Features, Limitations

What is CSS aspect-ratio?

CSS aspect-ratio is a CSS property from the CSS Box Sizing Module Level 4 specification of the W3C. It sets the preferred width-to-height ratio of an element's box so the browser keeps that ratio as the layout reflows. At least one of width or height must resolve to auto for the property to take effect.

Which browsers does CSS aspect-ratio support?

CSS aspect-ratio is Baseline Widely Available and ships in every modern desktop and mobile browser. Chrome 88, Edge 88, Firefox 89, Safari 15 on macOS and iOS, Opera 74, and Samsung Internet 15 all enable it by default, while Internet Explorer never received support.

What are the key features of CSS aspect-ratio?

CSS aspect-ratio replaces a stack of layout hacks with a single declarative property. The surface is small, but each feature solves a problem that used to need padding tricks or JavaScript.

• Direct ratio syntax: The property accepts a ratio like 16 / 9 or a single number like 0.5. The single-number form treats height as 1, so aspect-ratio: 2 means a 2:1 box. This replaces the old padding-top: 56.25% workaround for video embeds.
• Auto keyword for replaced elements: aspect-ratio: auto on an img or video uses the natural ratio of the loaded media. Pair auto with a fallback ratio, like aspect-ratio: 3 / 2 auto, and the box reserves 3:2 space until the image loads, then snaps to the file's real ratio.
• One-axis sizing: The property only fires when at least one axis is auto. Set width: 100% and aspect-ratio: 16 / 9 and height computes from the ratio. The box stays correct as the parent resizes, with no media-query ladder.
• Works on every layout mode: aspect-ratio applies in block flow, flexbox, and grid items. The browser respects min-width, max-width, min-height, and max-height boundaries, so the ratio yields when constraints clash instead of overflowing the parent.
• calc() and var() friendly: The property accepts calc(16 / 9) and CSS custom properties, so themed components can swap ratios through a single var(). This pairs cleanly with container queries to switch ratios at component breakpoints.

What are the use cases of CSS aspect-ratio?

CSS aspect-ratio shows up in production stacks any time a box needs to keep its shape across viewports. The property is now the default tool for several layout patterns that older sites still ship as JavaScript or padding hacks.

• Responsive video and iframe embeds: A YouTube or Vimeo iframe with width: 100%, height: auto, and aspect-ratio: 16 / 9 keeps a clean widescreen frame at every viewport width. This pattern ships on news sites, course platforms, and product pages without any padding-top trick.
• Image placeholders that prevent layout shift: Setting aspect-ratio: 3 / 2 auto on a lazy-loaded img reserves the right space before bytes arrive, which keeps the Cumulative Layout Shift score near zero. Image-heavy sites like e-commerce grids and editorial pages rely on this for Core Web Vitals.
• Card grids with consistent shape: A CSS Grid of cards each set to aspect-ratio: 4 / 3 produces a uniform mosaic without manual height clamping. The cards keep shape as the grid track count changes from one to four columns.
• Charts, maps, and SVG canvases: A data-visualization container with aspect-ratio: 2 / 1 ships the same proportion across desktop and phone, which simplifies the SVG viewBox math the chart library has to do on resize.
• App shells with avatar and thumbnail tiles: A square avatar with aspect-ratio: 1 / 1 and width: 48px is sturdier than width and height pairs because a typo in one axis no longer warps the circle. Chat lists, comment threads, and contact pickers all benefit.

How do you check if a browser supports CSS aspect-ratio?

The cleanest check is the @supports at-rule with a property and value pair. Wrap aspect-ratio rules so the browser only applies them when the engine parses the property, and pair the rule with @supports not to ship a padding-top fallback for older browsers.

/* Feature-detect aspect-ratio before applying it. The block runs only when
   the browser parses the property; older engines skip it and fall through
   to the @supports not block below. */
@supports (aspect-ratio: 1 / 1) {
    .video-embed {
        width: 100%;
        aspect-ratio: 16 / 9;
        height: auto;
    }
}

/* Padding-top fallback for browsers without aspect-ratio support. */
@supports not (aspect-ratio: 1 / 1) {
    .video-embed {
        position: relative;
        padding-top: 56.25%;
        height: 0;
    }

    .video-embed > iframe {
        position: absolute;
        inset: 0;
        width: 100%;
        height: 100%;
    }
}

For runtime checks, the CSS.supports JavaScript API parses the same property and value pair. Paste this snippet into the DevTools console of any browser to see whether the engine recognizes aspect-ratio.

// Paste into any browser DevTools console to check aspect-ratio support
// at runtime. CSS.supports parses the property and value pair and returns
// a boolean.

const supportsAspectRatio = CSS.supports('aspect-ratio', '1 / 1');
console.log(`aspect-ratio supported in this browser: ${supportsAspectRatio}`);

// Logs true on Chrome 88+, Edge 88+, Firefox 89+, Safari 15+, Opera 74+,
// and Samsung Internet 15+. Logs false on Internet Explorer and any
// browser older than the versions above.

If CSS.supports returns false, the browser silently ignores any rule that contains aspect-ratio. Use the @supports not block above to set padding-top space for those users instead of leaving the layout collapsed.

What are the known issues with CSS aspect-ratio?

CSS aspect-ratio is Baseline Widely Available, but the way browsers resolve the property next to other constraints still has rough edges that hit production sites. Plan around these before you replace padding-top hacks with aspect-ratio.

• Both width and height set kills the ratio: When both axes have explicit values, the browser uses those values and ignores aspect-ratio entirely. Leave at least one axis as auto, or the property is silently dropped.
• min-* and max-* constraints win: A min-width, max-width, min-height, or max-height boundary takes precedence over the ratio. A 16:9 box that hits its max-height stops scaling and the ratio breaks. Tune the constraints, or accept the ratio yielding at the bound.
• Flex stretching overrides ratios: A flex item inherits align-items: stretch from the parent, which can pull the cross axis to fill the row and ignore the ratio. Set align-items: flex-start on the parent or align-self: start on the item to keep the ratio.
• Content overflow expands the box: Long text or large children inside a ratio-locked box can force the box to expand past the ratio. Add min-height: 0 or overflow: hidden so overflow does not break the locked shape.
• auto serialization differences: Older Safari versions read aspect-ratio: auto 3 / 2 back from getComputedStyle in a different order than Chrome and Firefox. Match against numeric ratios in tests, not against the serialized auto string.

In my experience, the silent failure mode that bites teams the most is leaving width and height set on lazy-loaded img tags: the framework ships both attributes for layout-shift reasons, then aspect-ratio: 3 / 2 auto on the same image is ignored. Drop the height attribute on the markup and let aspect-ratio drive height for the auto behavior to actually fire.

Citations

All CSS aspect-ratio version numbers and platform notes in this guide come from these primary sources:

• W3C CSS Box Sizing Module Level 4, aspect-ratio property: w3.org/TR/css-sizing-4/#aspect-ratio
• MDN aspect-ratio CSS property: developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio
• MDN guide, Understanding aspect ratios: developer.mozilla.org/en-US/docs/Web/CSS/Guides/Box_sizing/Aspect_ratios
• MDN @supports at-rule: developer.mozilla.org/en-US/docs/Web/CSS/@supports
• MDN CSS.supports() static method: developer.mozilla.org/en-US/docs/Web/API/CSS/supports_static
• web.dev, The CSS aspect-ratio property: web.dev/articles/aspect-ratio
• Mozilla Firefox 89 release notes: firefox.com/en-US/firefox/89.0/releasenotes
• WebKit blog, Release Notes for Safari Technology Preview 122: webkit.org/blog/11577/release-notes-for-safari-technology-preview-118
• Wikipedia Cascading Style Sheets: en.wikipedia.org/wiki/Cascading_Style_Sheets