How to Use the CSS aspect-ratio Property

Use aspect-ratio to give a box a preferred width-to-height ratio, such as 16 / 9. The browser uses that preference when it calculates an automatic dimension; it does not force an element to that shape when both width and height are explicitly set.

1. Set a responsive aspect ratio

Write the width part first and the height part second. For a 16:9 box, the height is nine sixteenths of the width. A single number means that number divided by one, so aspect-ratio: 1 is square.

<div class="video-frame">
  <iframe src="https://example.com/embed/video" title="Video"></iframe>
</div>

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

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

Here the containing layout determines the available width, while the ratio provides preferred sizing for the automatic height. Other layout constraints, such as a maximum width or a fixed height, can affect the final size.

Common ratios include 1 / 1 for square tiles, 4 / 3 for a traditional landscape box, 16 / 9 for a widescreen frame, and 9 / 16 for a portrait frame. These are design choices, not special keywords.

2. Understand what the property controls

aspect-ratio is a preferred sizing ratio, not a pair of fixed dimensions. It participates in sizing when at least one relevant dimension is automatic. If both width and height have definite values, the ratio does not override them.

.automatic-height {
  width: 100%;
  height: auto;
  aspect-ratio: 16 / 9;
}

/* Both dimensions are definite: the ratio does not change these sizes. */
.fixed-box {
  width: 320px;
  height: 200px;
  aspect-ratio: 16 / 9;
}

For a basic non-replaced element, leave one dimension available for automatic sizing and set the ratio. In grid and flex layouts, min/max constraints and the available space still matter. If the result differs from the simple ratio calculation, inspect the computed width and height and the constraints coming from the parent and other CSS rules.

3. Use aspect ratios with images and other replaced content

Images, videos, and other replaced elements can have an intrinsic ratio supplied by their content. The box’s preferred ratio and the media’s natural ratio are related but distinct: setting a ratio controls sizing calculations, while fitting or cropping the image content is a separate choice.

<img class="thumbnail" src="photo.jpg" alt="A mountain lake">

.thumbnail {
  display: block;
  width: 100%;
  aspect-ratio: 4 / 3;
  object-fit: cover;
}

This makes a 4:3 image box and asks the image content to cover it, which may crop the content. Use object-fit: contain when the whole image should remain visible, with possible empty space inside the box. Do not assume aspect-ratio itself stretches or crops the image.

The property also accepts auto and a ratio together. For replaced content, auto 3 / 4 uses the element’s natural ratio when it has one; the specified ratio is the preferred fallback where there is no natural ratio. For ordinary elements without an intrinsic ratio, the specified ratio supplies the preference.

.media {
  aspect-ratio: auto 3 / 4;
}

4. Account for the box model

Ratio calculations use the dimensions associated with the element’s box-sizing. With content-box, declared width and height refer to the content box; with border-box, they refer to the border box. Padding and borders can therefore change the outside dimensions you measure.

.card {
  box-sizing: border-box;
  width: 100%;
  aspect-ratio: 4 / 3;
  padding: 1rem;
  border: 1px solid #bbb;
}

If a bordered card’s outside shape must be exactly 4:3, make the box-sizing choice explicit and check the dimensions you mean to constrain. A global box-sizing: border-box reset is common, but the important point is to reason about the same box—content, padding, or border—that your design measures.

5. Choose the right sizing pattern

Need	Pattern	What to check
Responsive box whose width comes from its parent	`width: 100%; aspect-ratio: 16 / 9;`	Keep the other dimension automatic; inspect min/max constraints.
Square tile	`aspect-ratio: 1;`	Do not set a conflicting definite height.
Image crop in a fixed-shape frame	`aspect-ratio: 4 / 3; object-fit: cover;`	Choose whether cropping is acceptable.
Use an image’s natural ratio when available	`aspect-ratio: auto;`	The source media needs an intrinsic ratio for this to help.
Natural ratio with a preferred fallback	`aspect-ratio: auto 3 / 4;`	Most useful for replaced content that may lack natural dimensions.
Both dimensions are intentionally fixed	Set width and height directly	`aspect-ratio` will not override both sizes.

6. Troubleshoot unexpected dimensions

The box ignores the ratio: check whether both width and height resolve to definite values. Leave one dimension automatic if you want the ratio to participate.
The box is not the expected size: inspect min-width, max-width, min-height, max-height, padding, borders, and parent layout constraints. The ratio is a preference within sizing, not a command to violate those constraints.
The image looks cropped or letterboxed: inspect object-fit. cover crops to fill; contain preserves the whole image with possible empty space. This is content fitting, separate from box sizing.
The outer dimensions do not match the ratio: verify box-sizing and decide whether the content box or border box must have the target ratio.
An iframe’s content does not fill its frame: give the iframe explicit width: 100% and height: 100%, and remove its border if appropriate. The parent’s ratio sizes the frame; it does not automatically size every child.
The image changes size after loading: provide intrinsic dimensions in the markup where known, or give the image a ratio and automatic sizing. Confirm the source’s natural dimensions and the final computed styles.

7. Performance, reliability, and compatibility

aspect-ratio is CSS sizing information; it does not fetch content or add a JavaScript measurement loop. Supplying a predictable box shape can help layout reserve the intended space while media loads, especially when the ratio is known. For images, intrinsic dimensions or a suitable ratio also help the browser calculate a box before the image is available.

Keep the ratio and the media fitting rule separate: the ratio describes the box, while object-fit describes how replaced content fits that box. For reliable layouts, test the real constraints at narrow and wide container sizes and with media whose intrinsic ratio differs from the frame.

The research sources used for this guide establish the syntax and sizing behavior but do not provide a version-by-version browser support matrix. Consult current compatibility data for the browsers your project supports before relying on a specific support baseline. See MDN’s aspect-ratio reference and its guide to understanding and setting aspect ratios.

8. Inspect a rendered page with ScreenshotNeo

When a responsive box looks right in CSS but wrong in a real page, compare captures at the viewport sizes your layout targets. ScreenshotNeo is a website screenshot API and MCP server for developers. It can capture pages at custom viewports and device presets, which helps inspect rendered layouts.

Or skip the browser setup

Make a one-call capture with cURL; replace the target URL with your page and use your API key. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are never billed. Response headers identify the page verdict and billing status.
An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf.
1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 shots. Every feature is on every plan.

9. FAQ

Can I write `aspect-ratio: 16 / 9` without a unit?

Yes. A ratio is unitless: the numbers express relative width and height parts.

Is `aspect-ratio` inherited?

No. Its initial value is auto, and it is not inherited.

Does setting an image ratio change the actual image file?

No. It affects the element’s sizing calculations. Use content-fitting rules such as object-fit to control how the image appears within its box.

Should I set both width and height along with a ratio?

Usually not when you expect the ratio to determine one dimension. If both dimensions are definite, they determine the preferred size and the ratio does not override them.