CSS aspect-ratio for Images, Frames, and Layouts

CSS aspect-ratio gives a box a preferred proportion while layout calculates its size. It is useful for square avatars, consistent thumbnails, and video frames when at least one dimension can remain automatic.

.video-frame {
  inline-size: 100%;
  aspect-ratio: 16 / 9;
}

A 16 / 9 ratio means the width is sixteen units for every nine units of height. It does not select a crop or resize the contents by itself.

CSS aspect-ratio needs room to calculate a dimension

The aspect-ratio reference describes a preferred ratio. If both width and height are definite, those sizes leave no automatic dimension for the ratio to determine.

Compare these rules:

.proportional-box {
  width: 320px;
  aspect-ratio: 16 / 9;
}

.fixed-box {
  width: 320px;
  height: 240px;
  aspect-ratio: 16 / 9;
}

The first can derive a height of 180px. The second has an explicit 240px height, so adding the ratio does not make it widescreen.

Minimum sizes and content constraints can also affect the result. When a box has the wrong shape, inspect its actual width, height, and min/max rules before changing the ratio again.

Give thumbnails a shape, then choose the crop

For consistent thumbnail boxes:

<img class="thumbnail" src="photo.jpg" width="1200" height="800"
     alt="A wooden footbridge crossing a narrow stream">

.thumbnail {
  display: block;
  width: 100%;
  height: auto;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

Replace the file, dimensions, and alternative text with the actual image’s details. The CSS requests a widescreen box; object-fit controls how the image fits inside it.

cover fills the box and can crop the source. contain keeps the whole image visible and can leave unused space. Neither choice is automatically right for every photograph or diagram.

A subject near the edge may need a different crop position:

.thumbnail {
  object-position: 70% 50%;
}

The object-position property moves the replaced content inside its box. Choose the value for the actual asset rather than copying one percentage across a whole gallery.

Distinguish a fixed ratio from an intrinsic fallback

A fixed ratio and a fallback for an unloaded image are different requests:

.fixed-ratio {
  width: 100%;
  height: auto;
  aspect-ratio: 4 / 3;
  object-fit: cover;
}

.natural-after-loading {
  width: 100%;
  height: auto;
  aspect-ratio: auto 4 / 3;
}

For a replaced element such as an image, auto 4 / 3 uses the supplied ratio until the intrinsic ratio is available. The natural ratio then takes over.

A plain aspect-ratio: 4 / 3 keeps requesting that ratio. It is not the fallback-and-switch behavior described by the second rule.

Keep real image width and height attributes when you know them. Reserving space for the correct proportions is more useful than an arbitrary placeholder that later changes shape.

Size an avatar with one dimension

A square avatar can use the same principle:

.avatar {
  width: 3rem;
  height: auto;
  aspect-ratio: 1;
  object-fit: cover;
  border-radius: 50%;
}

aspect-ratio: 1 supplies the square box, object-fit handles the image, and the radius makes the visible frame circular. Keeping those jobs separate makes each rule easier to change.

For a group of cards, the ratio also needs a sensible width constraint. A ratio alone does not explain how much room the card should occupy in the grid.

Let an iframe fill the frame you created

A wrapper can own the ratio while the embedded content fills it:

<div class="video-frame">
  <iframe src="https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ"
          title="Big Buck Bunny video" loading="lazy" allowfullscreen></iframe>
</div>

.video-frame > iframe {
  display: block;
  width: 100%;
  height: 100%;
  border: 0;
}

The earlier .video-frame rule supplies the wrapper’s width and ratio. Replace the embed URL and title for your own video; the ratio does not make a third-party embed private or cost-free.

For a new layout, I would use the ratio to describe the box and let the content-fitting rules describe what happens inside it. That avoids returning to a padding hack when the real issue is a fixed height or an unsuitable crop.

← Back to all articles