Every element rendered to the page has a height and a width, and, therefore, anaspect ratio, which is the ratio between the width and height. The natural dimensions of a media object, which are its size without any sizing, scaling, zooming, or borders applied, are known as its natural orintrinsic size. An element's intrinsic size is determined by the element itself, not by applying formatting such asbox sizing or setting border, margin, or padding widths.

When developing sites, you often want to be able to set the width of an element to a percentage of the viewport or parent container size and have the height change size proportionally, thereby maintaining a specific aspect ratio depending on the size of the viewport. For replaced elements, like images and videos, maintaining a specific aspect ratio is not only necessary for creatingresponsive web design, but also a vital component of providing good user experience. Setting an asset's aspect ratio prevents loadingjank—the layout shift that occurs when media loads after the page has already been painted, causing a reflow because the space for the asset has not been reserved.

Using CSS, you can adjust the size of replaced and non-replaced elements based on their aspect ratio. In this guide, we will learn about theaspect-ratio property, discuss aspect ratios for replaced and non-replaced elements, and then examine some common aspect ratio use cases.

How theaspect-ratio property works

The CSSaspect-ratio property value defines the preferred width-to-height ratio of an element's box. The value is either a<ratio>, the keywordauto, 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;

<div>0.5</div><div>1.5</div>

div {  height: 121px;  aspect-ratio: 0.5;  background-color: pink;  line-height: 100px;  text-align: center;  float: left;  background-image:    repeating-linear-gradient(to right, black 0px 1px, transparent 1px 20px),    repeating-linear-gradient(black 0px 1px, transparent 1px 20px);  background-size:    181px 5px,    5px 121px;  background-repeat: no-repeat;}div + div {  aspect-ratio: 1.5;  background-color: lightgreen;  margin-left: 10px;}

The effect of theauto 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, theauto value means the box has no preferred aspect ratio. In both cases, this is the default behavior as if noaspect-ratio property were applied.

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

You will have noticed the word "preferred" in the definitions above. Theaspect-ratio value is not always applied when set. Theaspect-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, theaspect-ratio property value is ignored. In this case, no dimension is allowed to be automatically sized - the preferred sizes are explicitly set - so theaspect-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 thanauto) to either dimension, both will default to their intrinsic size (anyaspect-ratio value isn't applied). Theaspect-ratio will apply to non-replaced elements that don't have a dimension explicitly set, as non-replaced elements are eitherintrinsically orextrinsically 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.

Adjusting aspect ratios of replaced elements

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.

<img  src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg?image=good"  alt="220 pixel square pride flag" />

This is a220px 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 forwidth, 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 thewidth 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 of220px via thewidth: auto value.

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

img {  width: 55px;  margin-right: 5px;}img + img {  width: 110px;}img + img + img {  width: auto;}

Only when you provide sizes for both dimensions is there a risk of distorting the replaced element. For example, settingwidth: 100vw; andheight: 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 sameheight value (110px) but differentwidth values (55px,110px, and220px).

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

img {  width: 55px;  height: 110px;}img + img {  width: 110px;}img + img + img {  width: 220px;}

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

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

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

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

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

Fitting replaced elements within their containers

To fit a replaced element to the dimensions of its container while maintaining its intrinsic aspect ratio, set theobject-fit property value tocover orcontain. 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 of5 / 2.

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

<div>  <div>    <img      src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"      alt="Pride flag" />  </div>  <div>    <img           src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"      alt="Pride flag" />  </div>  <div>    <img           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 of2.5 (5/2) with a minimum width of150px. Therefore, the minimum height will be60px. 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: #cccccc;}

We then size the images and set theobject-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 thefill value ofobject-fit to create the same effect. Thecover image spans the full width of the container, centered vertically, and clipped to fit in the container. Thecontain value ensures the image is contained within the container, centered horizontally, and shrunk to fit.

Defining aspect ratios for non-replaced elements

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 in200px and600px wide containers, and a square is set with a height matching its200px width:

<p>Narrow:</p><blockquote>  <q    >When you stop living your life based on what others think of you real life    begins. At that moment, you will finally see the door of self acceptance    opened.</q  >  - Shannon L. Alder</blockquote><p>Wide:</p><blockquote>  <q    >When you stop living your life based on what others think of you real life    begins. At that moment, you will finally see the door of self acceptance    opened.</q  >  - Shannon L. Alder</blockquote><p>Aspect ratio with overflow:</p><blockquote>  <q    >When you stop living your life based on what others think of you real life    begins. At that moment, you will finally see the door of self acceptance    opened.</q  >  - Shannon L. Alder</blockquote><p>  <label    ><input type="checkbox" checked /> Toggle between    <code>overflow</code> values <code>auto</code> and    <code>visible</code></label  ></p>

To highlight the issue with setting a non-replaced element's aspect ratio via size dimensions, toggle theoverflow property betweenauto andvisible.

blockquote {  border: 3px dotted #cccccc;  padding: 0 3px;  margin: 20px 0;  font-size: 1.25rem;  line-height: 1.5;}body:has(:checked) blockquote {  overflow: auto;}:checked + code,:not(:checked) + code + code {  outline: 1px solid green;}p:nth-last-of-type(n + 2) {  font-weight: bold;}

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 CSSaspect-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 settingaspect ratio: 1 on<blockquote>, a non-replaced element:

<p>Short text:</p><blockquote>Breath.</blockquote><p>Longer text:</p><blockquote>You're perfect just as you are.</blockquote>

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

blockquote {  border: 1px solid #cccccc;  padding: 1px;  margin: 20px 0;  background-color: #ededed;}

Each box has one dimension defined: theinline-size, which is the width in horizontal languages, is set tomax-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, theblock-size orheight, is set to be the same length as the first dimension. This is accomplished with theaspect-ratio property. We defined the desired width-to-height ratio of the element's box to be1, which is the same as1 / 1, a square. This sets the block direction to match the width of the element, without using theheight orblock-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.

Creating a circle based on the container size

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

In this example, we have a container<div> that is200px wide, which includes5px of padding on each side. Therefore, the inline-size of the content box is190px. Without setting a height or width on the nested<p> element, we know its inline-size is190px. Withaspect-ratio: 1 set, the paragraph will be190px 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 the190px tall paragraph, the5px 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 aborder-radius of50%, so the container is an oval while the child, with anaspect-ratio of1 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;  border: 1px solid black;  background-color: #66ccff;}p {  aspect-ratio: 1;  text-align: center;  border: 10px solid white;  background-color: #f4aab9;}

To make the<div> a circle, we can set theheight andwidth to the same value, or setaspect-ratio: 1 and set theoverflow toauto orhidden. Alternatively, we can simply remove the margins on the paragraph withmargin-block: 0. Both these options are shown below.

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

div {  width: 200px;  padding: 5px;  margin: 1rem;  border: 1px solid black;  background-color: #66ccff;}p {  text-align: center;  border: 10px solid white;  background-color: #f4aab9;}

div,p {  aspect-ratio: 1;  border-radius: 50%;}div:first-of-type {  overflow: hidden;}div:last-of-type p {  margin-block: 0;}

Commonaspect-ratio use cases

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

Making external assets responsive

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 to100% of its container or100vw 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 theaspect-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 theaspect-ratio feature within the@media query alongside theaspect-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;  }}

Making grid cells square

A grid of square cells can be created by defining fixedcolumn track sizes, ensuring each row matches the size of the column track. However, when creating responsive grids usingauto-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 least95px wide but could be much wider. No matter the width, each item will be a square, with the height determined by theaspect-ratio to match its width.

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

div {  gap: 20px;  font-size: 1.1rem;}div div {  background-color: #cccccc;  aspect-ratio: 1;  counter-increment: items;}div div::after {  content: counter(items);}.item::after {  /*  hide the number if there's content  */  position: absolute;  color: transparent;}

<div>  <div></div>  <div></div>  <div>    This text would overflow the parent, but we've set properties to prevent it    from doing so.  </div>  <div></div>  <div></div>  <div></div>  <div>    <img      src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"      alt="Pride flag" />  </div>  <div></div>  <div></div>  <div></div>  <div></div>  <div></div>  <div></div>  <div></div>  <div></div></div>

For the content of a grid item to not grow beyond the preferred height set by theaspect-ratio, set themin-height to0 and theoverflow to a value other thanvisible. 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 themax-height (ormax-width, depending on the content) to100%.

.item {  min-height: 0;  overflow: auto;}.item > * {  max-height: 100%;}

Specifications

See also

• CSS box sizing module