Skip to main content
  • Created:
  • Updated:
  • Author:
    Takeshi Takatsudo

aspect-ratio

The Problem​

Maintaining aspect ratios for images, videos, embedded content, and card layouts is a common requirement. For years, the only reliable technique was the "padding-top hack" — using percentage-based padding to create a proportional box. AI agents often still generate the old hack or, worse, use fixed pixel dimensions that break on different screen sizes. The modern aspect-ratio property solves this in a single line with no extra markup.

The Solution​

The aspect-ratio CSS property sets a preferred aspect ratio for an element. The browser adjusts the element's dimensions to maintain this ratio, and content that exceeds the ratio can overflow or be handled with overflow or object-fit.

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

This is all that is needed. No wrapper divs, no absolute positioning, no percentage padding calculations.

Code Examples​

Basic Image with Aspect Ratio​

.thumbnail {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
  border-radius: 0.5rem;
}
<img class="thumbnail" src="photo.jpg" alt="Landscape photo" />

The image fills its container width and maintains a 16:9 ratio. object-fit: cover ensures the image fills the box without distortion, cropping if necessary.

aspect-ratio: Image Container (16/9)

Responsive Video Container​

.video-wrapper {
  width: 100%;
  aspect-ratio: 16 / 9;
}

.video-wrapper iframe {
  width: 100%;
  height: 100%;
  border: 0;
}
<div class="video-wrapper">
  <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" allowfullscreen></iframe>
</div>

Square Card Grid​

.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 200px), 1fr));
  gap: 1rem;
}

.card {
  aspect-ratio: 1;  /* Square */
  overflow: hidden;
  border-radius: 0.5rem;
}

.card img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}
<div class="card-grid">
  <div class="card"><img src="1.jpg" alt="" /></div>
  <div class="card"><img src="2.jpg" alt="" /></div>
  <div class="card"><img src="3.jpg" alt="" /></div>
</div>
aspect-ratio: Card Layout Grid

Aspect Ratio with Fallback Content​

When content might overflow the aspect ratio box:

.card-fixed {
  aspect-ratio: 4 / 3;
  overflow: hidden;
  padding: 1rem;
}

If the content is taller than the 4:3 ratio allows, it is clipped. For scrollable overflow, use overflow: auto instead.

The Old Padding-Top Hack (For Reference)​

This is the legacy technique that AI agents should stop generating:

/* OLD: padding-top hack — do not use in new code */
.video-wrapper-old {
  position: relative;
  width: 100%;
  padding-top: 56.25%; /* 9/16 = 0.5625 */
  height: 0;
}

.video-wrapper-old iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
/* NEW: aspect-ratio — use this instead */
.video-wrapper-new {
  width: 100%;
  aspect-ratio: 16 / 9;
}

.video-wrapper-new iframe {
  width: 100%;
  height: 100%;
}

The modern version is shorter, more readable, requires no wrapper trickery, and does not misuse the padding property.

Preventing Layout Shift on Images​

Setting aspect-ratio on images reserves space before the image loads, preventing Cumulative Layout Shift (CLS):

img {
  aspect-ratio: attr(width) / attr(height);
  width: 100%;
  height: auto;
}

In practice, browsers already compute aspect ratio from the width and height HTML attributes. Always include both attributes on <img> tags:

<!-- Good: browser reserves space using width/height ratio -->
<img src="photo.jpg" alt="Photo" width="800" height="450" />

<!-- Bad: no dimensions, causes layout shift -->
<img src="photo.jpg" alt="Photo" />

Circle Avatar​

.avatar {
  width: 3rem;
  aspect-ratio: 1;
  border-radius: 50%;
  object-fit: cover;
}
<img class="avatar" src="user.jpg" alt="User avatar" />

Common AI Mistakes​

  • Still generating the padding-top hack. The aspect-ratio property has had full browser support since 2021 (96%+ global coverage). The padding hack is no longer needed for any modern browser target.
  • Forgetting object-fit on images. Setting aspect-ratio on an <img> without object-fit: cover (or contain) causes the image to distort if its natural ratio differs from the specified ratio.
  • Using fixed pixel dimensions instead of aspect-ratio. AI agents often set width: 640px; height: 360px for a 16:9 element. This breaks on smaller screens. Use width: 100%; aspect-ratio: 16 / 9 for responsive behavior.
  • Not including width and height attributes on <img> tags. These attributes allow the browser to reserve the correct space before the image loads, preventing layout shift. This is a Core Web Vitals requirement.
  • Setting both width and height in CSS alongside aspect-ratio. If both dimensions are explicitly set, aspect-ratio has no effect. Set one dimension (usually width) and let aspect-ratio calculate the other.
  • Using aspect-ratio on flex/grid items without understanding how it interacts with stretching. In a flex container with align-items: stretch (the default), the item's height is determined by the container, which overrides aspect-ratio. Set align-items: flex-start or align-self: start on the item.

When to Use​

aspect-ratio is ideal for​

  • Images and image placeholders to prevent layout shift
  • Video embeds (YouTube, Vimeo iframes)
  • Card layouts that need consistent proportions
  • Avatar images (use aspect-ratio: 1 for squares/circles)
  • Hero sections with fixed proportions
  • Any element that must maintain a width-to-height relationship

Use object-fit alongside aspect-ratio when​

  • The content (image or video) may not match the specified ratio
  • cover fills the box completely, cropping edges if needed
  • contain fits the entire content inside the box, leaving empty space

Keep the padding-top hack only when​

  • You must support Internet Explorer (end-of-life since June 2022)
  • Working in a legacy codebase that cannot be updated yet

References​

Last updated on by Takeshi Takatsudo