CSS aspect-ratio Property

This property allows you to define a preferred proportional relationship between the width and height of an element box.

selector { aspect-ratio: auto | <ratio>; }
auto Uses the intrinsic aspect ratio of the element if it exists, otherwise no ratio is applied.
<ratio> A width-to-height ratio specified as two numbers separated by a forward slash, like 16 / 9.
auto <ratio> Uses the intrinsic ratio of an element like an image if available; if not, it falls back to the specified ratio.

Code Examples

A basic example showing a responsive container that maintains a 16:9 cinematic aspect ratio regardless of its width.

<div style="width: 100%; max-width: 500px; aspect-ratio: 16 / 9; background-color: #333333; color: #ffffff; display: flex; align-items: center; justify-content: center;">
  16:9 Cinema Container
</div>

An advanced example using JavaScript to toggle between a square and an ultra-wide aspect ratio dynamically.

<div id="box" style="width: 200px; aspect-ratio: 1 / 1; background-color: #ff5733; margin-bottom: 10px;"></div>
<button onclick="toggleRatio()">Change to Wide</button>

<script>
function toggleRatio() {
  const box = document.getElementById("box");
  if (box.style.aspectRatio === "1 / 1") {
    box.style.aspectRatio = "21 / 9";
    box.style.width = "400px";
  } else {
    box.style.aspectRatio = "1 / 1";
    box.style.width = "200px";
  }
}
</script>

Pro Tip

You can use the aspect-ratio property on container placeholders for third-party ads. Since you often know the size of the ad unit beforehand, setting the ratio ensures the rest of your page layout remains rock solid while the ad script is fetching the creative assets.

Deep Dive

Think of aspect-ratio like a picture frame that stays the same shape no matter how large the wall is. Before this property existed, web developers had to use the padding-top hack, which felt like building a house with duct tape. Now, you simply tell the browser the ratio you want, and it handles the math. If you set the width to 100%, the browser calculates the height automatically based on your ratio. It effectively turns one dimension into a function of the other. It is particularly useful for responsive layouts where you want containers to scale while maintaining a specific look, like a video player or a square profile card. Note that if you explicitly define both width and height, the ratio property will be ignored because you have already manually dictated the dimensions.

Best Practices

Use this property to reserve space for images or videos before they load. This prevents Cumulative Layout Shift (CLS), which is that annoying jump you see on a page when a big image finally pops in and pushes the text down. It is also great for creating flexible grids where every item needs to be a perfect square or a cinematic rectangle regardless of the screen size. Always test how the element behaves when the content inside is larger than the ratio allows, as the content might overflow the box.

Common Pitfalls

The most common mistake is setting both a width and a height. If you do that, aspect-ratio is rendered useless because the fixed dimensions take priority. Another gotcha is forgetting that the element might expand to fit its content by default. If your content is too tall for the ratio you set, the box will often stretch to prevent data loss unless you specifically control the overflow or set a min-height.

Accessibility

By maintaining layout stability, you are helping users with cognitive disabilities or those who use screen magnifiers. A stable layout means the user does not lose their place when assets load in. It provides a more predictable experience, which is a win for everyone.

Dev Data Table: aspect-ratio property

default auto
animatable yes
inherited no
experimental no
year_intro 2020
year_standard 2021
js_syntax_1 element.style.aspectRatio = "16 / 9";
js_syntax_2 element.style.setProperty("aspect-ratio", "1 / 1");
js_note In JavaScript, ensure the ratio is passed as a string and remember that browsers calculate this value dynamically based on the available space.
browsers { "Chrome": 88, "Edge": 88, "Firefox": 89, "Safari": 15, "Opera": 74, "Chrome Android": 88, "Safari on iOS": 15, "Samsung Internet": 15, "Opera Mobile": 63 }
results render here...