Codectionary / Developer documentation / CSS

aspect-ratio

aspect-ratio sets a preferred width-to-height ratio for an element, letting the browser automatically calculate one dimension from the other. This replaced older, hackier techniques (like the "padding-top trick") for maintaining consistent proportions on responsive elements like video embeds and images.

Syntax

aspect-ratio: width / height;

Examples

A Responsive Video Embed

The classic use case - maintaining a 16:9 ratio at any width.

/* Demo setup: sizing, structure or neutral surfaces. */
iframe{border:0;display:block}

.video-embed {
  width: 100%;
  aspect-ratio: 16 / 9; /* height is calculated automatically to maintain the ratio */
}

.video-embed iframe {
  width: 100%;
  height: 100%;
}
  1. The local frame avoids a missing video URL or third-party embed restriction.
  2. The wrapper’s aspect ratio controls its automatic height as its width changes.
  3. This is a ratio demonstration, not a video player or a claim that arbitrary media can play.
HTML used by this example
<div class="video-embed"><iframe title="Local demonstration frame" srcdoc="<body style='margin:0;background:#064e3b;color:white;display:grid;place-items:center;font:20px sans-serif'>16:9 local frame</body>"></iframe></div>

Square Thumbnails and Image Placeholders

Reserving consistent space before an image loads, preventing layout shift.

/* Demo setup: sizing, structure or neutral surfaces. */
.thumbnail{max-width:16rem}

.thumbnail {
  width: 100%;
  aspect-ratio: 1 / 1; /* always a perfect square */
  object-fit: cover;
}
  1. The original landscape is placed in the thumbnail box.
  2. A square aspect ratio controls the box shape; object-fit controls how the non-square image fits within it.
  3. Resize the box and compare cover with contain to see cropping versus empty space.
HTML used by this example
<img class="thumbnail" src="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22240%22%20viewBox%3D%220%200%20480%20240%22%3E%3Crect%20width%3D%22480%22%20height%3D%22240%22%20fill%3D%22%23e0f2fe%22%2F%3E%3Ccircle%20cx%3D%22365%22%20cy%3D%2255%22%20r%3D%2230%22%20fill%3D%22%23fbbf24%22%2F%3E%3Cpath%20d%3D%22M0%20240%20135%2055%20280%20240%22%20fill%3D%22%230f766e%22%2F%3E%3Cpath%20d%3D%22m150%20240%20155-150%20175%20150%22%20fill%3D%22%235b21b6%22%2F%3E%3Ctext%20x%3D%2220%22%20y%3D%22218%22%20fill%3D%22white%22%20font-size%3D%2224%22%20font-family%3D%22sans-serif%22%3EOriginal%20landscape%3C%2Ftext%3E%3C%2Fsvg%3E" alt="A sun above green and purple mountains">

Parameters and values

  • aspect-ratio (width / height | auto): Sets a preferred proportional relationship between width and height

Best practices

  • Use aspect-ratio instead of the old "padding-top percentage" hack for maintaining proportions - it is far more readable and intuitive
  • Combine aspect-ratio with object-fit: cover on images/videos so content fills the box correctly without distortion
  • Reserve consistent aspect-ratio space for images before they load, to prevent content from jumping around during page load (improves Cumulative Layout Shift)
  • Remember explicit width/height attributes on <img>/<video> elements still matter for aspect-ratio to work correctly without JavaScript

Browser compatibility

chrome
Yes
firefox
Yes
safari
Yes
edge
Yes

These are the existing reference’s support labels, not tested minimum versions. Individual values and APIs can have different support. Check the linked specification before choosing a browser target.

CSS specifications (modules)

Specifications & further reading