Understanding and setting aspect ratios

The CSS aspect-ratio property value defines the preferred width-to-height ratio of an element's box. The value is either a <ratio>, the keyword auto, or a space-separated combination of both.

The <ratio> is the ratio of the width and height, in that order. It is represented by two positive <number> values separated by a forward slash (/) or a single <number>. When a single number is used, it is the same as writing the ratio as <number> / 1, which is also the width divided by the height.

The following values are all equivalent:

aspect-ratio: 3 / 6;
aspect-ratio: 1 / 2;
aspect-ratio: 0.5 / 1;
aspect-ratio: 0.5;

The following values are also all equivalent:

aspect-ratio: 9/6;
aspect-ratio: 3/2;
aspect-ratio: 1.5;

The effect of the auto keyword depends on whether the element on which it is applied is a replaced element or not. For replaced elements with an intrinsic aspect ratio, auto means the intrinsic aspect ratio should be used. In all other instances, the auto value means the box has no preferred aspect ratio. In both cases, this is the default behavior as if no aspect-ratio property were applied.

When the value contains both the auto keyword and a <ratio> value, such as aspect-ratio: auto 2 / 3; or aspect-ratio: 0.75 auto;, the auto value is applied to replaced elements with a natural aspect ratio and the specified ratio of the width / height or <number> is used as the preferred aspect ratio.

You will have noticed the word "preferred" in the definitions above. The aspect-ratio value is not always applied when set. The aspect-ratio property sets a "preferred" aspect ratio, so only ever has an effect if at least one of the box's sizes is automatic.

When both the height and width or inline and block sizes are explicitly set, the aspect-ratio property value is ignored. In this case, no dimension is allowed to be automatically sized - the preferred sizes are explicitly set - so the aspect-ratio property has no effect. When you declare both the inline and block dimensions, those take precedence.

With replaced elements, if you don't explicitly set a value (other than auto) to either dimension, both will default to their intrinsic size (any aspect-ratio value isn't applied). The aspect-ratio will apply to non-replaced elements that don't have a dimension explicitly set, as non-replaced elements are either intrinsically or extrinsically sized, getting their size from their content, container, box model properties, etc.

When an element is rendered to the page, if no CSS is applied and no HTML sizing attributes are included, the user agent will render the object at its natural size.

Replaced elements like <img> and <video> are replaced with media that have set dimensions and, therefore, an intrinsic aspect ratio. Consider a raster image, such as a JPEG, PNG, or GIF. If you place an image on a page and do not set a height or width, either via <img> attributes or with CSS, it will be displayed at its intrinsic size.

This is a 220px square image with no CSS applied; it is displayed at its intrinsic or default size.

If replaced content is auto-sized or you provide a size for only one dimension, such as setting a value for width, the browser will automatically resize the other dimension, in this case, the height, while maintaining the media's original aspect ratio.

In this example, only the width is set on the image, so the user agent preserves its aspect ratio. The same image is repeated three times, displayed at different widths: 55px, 110px, and at its natural size of 220px via the width: auto value.

Only when you provide sizes for both dimensions is there a risk of distorting the replaced element. For example, setting width: 100vw; and height: 100vh; on an image creates a variable aspect ratio; the image will appear either stretched or squashed when the viewport's aspect ratio differs from the image's natural aspect ratio.

In this example, the same image is repeated three times, explicitly sized with the same height value (110px) but different width values (55px, 110px, and 220px).

We have distorted the images intentionally by setting both a height and width: we've squashed the first one and stretched the third.

We could have created this same distorted effect using the CSS aspect-ratio property, by setting a single dimension (not both or neither) and providing a value other than 1 (or 1 / 1). You likely don't want to do this, but it's good to know that it's possible.

img {
  height: 100vh;
  aspect-ratio: 3;
}

We have declared a single dimension; 100vh is the full height of the example <iframe> viewport. For aspect-ratio to apply to replaced elements, only one dimension must be set. Setting both or neither doesn't work.

To fit a replaced element to the dimensions of its container while maintaining its intrinsic aspect ratio, set the object-fit property value to cover or contain. This will resize the replaced element and either clip it to "cover" the container or display it at a smaller size, fully "contained" within it.

In this example, the square image is placed into a grid of three items, each with an aspect ratio of 5 / 2.

To begin with, we create a container with three items, each containing one image:

<div class="grid">
  <div>
    <img
      src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
      alt="Pride flag" />
  </div>
  <div>
    <img
      class="cover"
      src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
      alt="Pride flag" />
  </div>
  <div>
    <img
      class="contain"
      src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
      alt="Pride flag" />
  </div>
</div>

Next, we designate the container as a grid, where each item has an aspect ratio of 2.5 (5/2) with a minimum width of 150px. Therefore, the minimum height will be 60px. However, the final width and height are determined by the width of the example's iframe, which will be based on your viewport size:

.grid {
  display: grid;
  gap: 20px;
  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
  font-size: 0; /* to minimize whitespace */
}

div div {
  aspect-ratio: 5 / 2;
  background-color: #ccc;
}

We then size the images and set the object-fit property on the last two images:

img {
  height: 100%;
  width: 100%;
}

.cover {
  object-fit: cover;
}

.contain {
  object-fit: contain;
}

Only the first image is distorted (stretched). We could have used the fill value of object-fit to create the same effect. The cover image spans the full width of the container, centered vertically, and clipped to fit in the container. The contain value ensures the image is contained within the container, centered horizontally, and shrunk to fit.

While the aspect ratio of a replaced element is maintained by default, adjusting the intrinsic size of a non-replaced element usually changes its aspect ratio. For example, identical content may appear as three lines on a widescreen or in a wide parent container, but as eight lines on a narrow screen or container.

In this example, the same quote is displayed in 200px and 600px wide containers, and a square is set with a height matching its 200px width:

To highlight the issue with setting a non-replaced element's aspect ratio via size dimensions, toggle the overflow property between auto and visible.

blockquote {
  width: 200px;
}

blockquote:nth-of-type(2) {
  width: 600px;
}

blockquote:nth-of-type(3) {
  height: 200px;
}

While it's possible to define an aspect ratio on non-replaced elements by setting both the dimensions and hiding overflowing content, the CSS aspect-ratio property provides explicit aspect ratio support. This means a specific aspect ratio can be set even when you don't know the content or screen sizes.

In the next example, we render square boxes regardless of the width of the text by setting aspect ratio: 1 on <blockquote>, a non-replaced element:

blockquote {
  inline-size: max-content;
  aspect-ratio: 1;
}

Each box has one dimension defined: the inline-size, which is the width in horizontal languages, is set to max-content, which sets the size to be as wide as it needs to be to fit the content without wrapping. The second dimension, in this case, the block-size or height, is set to be the same length as the first dimension. This is accomplished with the aspect-ratio property. We defined the desired width-to-height ratio of the element's box to be 1, which is the same as 1 / 1, a square. This sets the block direction to match the width of the element, without using the height or block-size properties.

In these examples, a size was explicitly set on the element itself. When working with non-replaced elements, aspect ratio comes into play when no size dimension is explicitly set.

The inline-size of non-replaced block-level elements is the size of their container's content box. Because they have a size by default, they don't need to have an explicit size set for the aspect-ratio property to work.

In this example, we have a container <div> that is 200px wide, which includes 5px of padding on each side. Therefore, the inline-size of the content box is 190px. Without setting a height or width on the nested <p> element, we know its inline-size is 190px. With aspect-ratio: 1 set, the paragraph will be 190px tall, unless it has visible overflowing content causing it to be taller (which it doesn't).

The height of the <div> element is not explicitly set, but it contains the 190px tall paragraph, the 5px of padding on top and bottom, and the combined heights of the default top and bottom margins of <p>. As a result, it is taller than it is wide. Both elements have a border-radius of 50%, so the container is an oval while the child, with an aspect-ratio of 1 but no inline or block sizing explicitly defined, is a circle.

<div><p>Hello world</p></div>

div,
p {
  border-radius: 50%;
}

div {
  width: 200px;
  padding: 5px;
  background-color: #66ccff;
}

p {
  aspect-ratio: 1;
  text-align: center;
  border: 10px solid #ffffff;
  background-color: #f4aab9;
}

To make the <div> a circle, we can set the height and width to the same value, or set aspect-ratio: 1 and set the overflow to auto or hidden. Alternatively, we can simply remove the margins on the paragraph with margin-block: 0. Both these options are shown below.

<section>
  <div><p>Hello world</p></div>
  <div><p>Hello world</p></div>
  <section></section>
</section>

div,
p {
  aspect-ratio: 1;
  border-radius: 50%;
}

div:first-of-type {
  overflow: hidden;
}

div:last-of-type p {
  margin-block: 0;
}

Let's look at a few situations where you can use aspect-ratio to address some common challenges while creating responsive designs.

All content should be responsive, even when that content is third-party embeds, such as videos from TikTok, YouTube, or Instagram. The code snippet you include to embed these external videos generally creates an <iframe>.

While a <video> element typically adopts the aspect ratio of its media file, iframe elements lack this capability. This poses the challenge of ensuring that the <iframe> is responsive while always maintaining the aspect ratio of the video it contains. One of the techniques we can use is to set the iframe's width to 100% of its container or 100vw to match the viewport width regardless of the viewport's size. However, setting a fixed height might stretch or squash the video. Instead, we set the aspect-ratio on the video's container, aligning it to be the same aspect ratio as the video. Problem solved!

For context, the standard aspect ratio of YouTube videos is 16:9 when viewed on a desktop computer or laptop, while TikTok and Instagram videos have a 9:16 aspect ratio.

.youtube {
  aspect-ratio: 16/9;
}

.instagram,
.tiktok {
  aspect-ratio: 9/16;
}

We can use the aspect-ratio feature within the @media query alongside the aspect-ratio property to adjust the size of both the iframe and the video it contains. This ensures that the video content is always as large as possible - taking up either the full width or height of the viewport, regardless of the viewport size - while maintaining a specific aspect ratio.

We can set the landscape-oriented YouTube videos to be as wide as the viewport and the portrait-oriented TitTok and Instagram video iframes to be as tall as the viewport. If a viewport's aspect ratio is wider than 16:9, we set the YouTube video to be the height of the viewport. If the viewport is narrower than 9:16, we set both Instagram and TikTok videos to the width of the viewport.

iframe.youtube {
  aspect-ratio: 16/9;
  width: 100vw;
  height: auto;
}

iframe.instagram,
iframe.tiktok {
  aspect-ratio: 9/16;
  height: 100vh;
  width: auto;
}

/* If the viewport is very wide but not very tall */
@media (aspect-ratio > 16 / 9) {
  iframe.youtube {
    width: auto;
    height: 100vh;
  }
}

/* If the viewport is very tall but not very wide */
@media (aspect-ratio < 9 / 16) {
  iframe.instagram,
  iframe.tiktok {
    height: auto;
    width: 100vw;
  }
}

A grid of square cells can be created by defining fixed column track sizes, ensuring each row matches the size of the column track. However, when creating responsive grids using auto-fill to fit as many column tracks as possible within the container, the width of each item becomes uncertain. This makes it challenging to determine the appropriate height for creating square items.

By setting an aspect ratio on the items, we can ensure when the grid items are laid out, each grid item will be as tall as it is wide, creating square grid items regardless of the container's dimensions.

In this example of square grid items, the grid tracks are auto-sized, taking their size from the items. Each item will be at least 95px wide but could be much wider. No matter the width, each item will be a square, with the height determined by the aspect-ratio to match its width.

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(95px, 1fr));
}

.item {
  aspect-ratio: 1;
}

For the content of a grid item to not grow beyond the preferred height set by the aspect-ratio, set the min-height to 0 and the overflow to a value other than visible. This will work for intrinsically sized content. If you have content that is intrinsically larger than the available space, set that content to not be larger than the grid item by setting the max-height (or max-width, depending on the content) to 100%.

.item {
  min-height: 0;
  overflow: auto;
}

.item > * {
  max-height: 100%;
}

• CSS box sizing module