HTML Guides for aspect-ratio

The aspect-ratio CSS property defines the preferred width-to-height ratio of an element’s box. Browsers use this ratio when calculating auto sizes and performing other layout functions, adjusting the element’s dimensions to maintain the specified proportion even as the parent container or viewport changes size.

The ratio is expressed as <width> / <height>. If the slash and height portion are omitted, height defaults to 1. So aspect-ratio: 2 is equivalent to aspect-ratio: 2 / 1. The property also accepts the auto keyword, which tells the element to use its intrinsic aspect ratio (if it has one), and a combined form like auto 3 / 4, which prefers the intrinsic ratio but falls back to the specified one.

This validation error typically occurs for several reasons:

• Using invalid separators or syntax, such as a colon (:) instead of a slash (/), e.g., aspect-ratio: 16:9.
• Providing units, such as aspect-ratio: 16px / 9px. The values must be unitless positive numbers.
• Using zero or negative numbers, which are not valid. Both parts of the ratio must be positive (> 0).
• Providing a string or unrecognized keyword, such as aspect-ratio: wide or aspect-ratio: "16/9".
• Missing spaces around the slash, though this is less common — 16/9 may work in browsers but the canonical form uses spaces: 16 / 9.
• Using the property in inline style attributes validated against an older CSS level where aspect-ratio wasn’t yet recognized by the validator.

Getting this value right matters for layout consistency across browsers. An invalid value will be ignored entirely by the browser, meaning the element won’t maintain any aspect ratio, potentially breaking your design. It’s especially important for responsive images, video containers, and card layouts where maintaining proportions is critical.

Examples

Incorrect: using a colon as the separator

<div style="aspect-ratio: 16:9; width: 100%;"></div>

The colon syntax (common in video specifications) is not valid CSS. The validator will reject 16:9 as an aspect-ratio value.

Incorrect: using units in the ratio

<div style="aspect-ratio: 16px / 9px; width: 100%;"></div>

The ratio values must be unitless numbers. Adding px or any other unit makes the value invalid.

Incorrect: using zero in the ratio

<div style="aspect-ratio: 0 / 1; width: 100%;"></div>

Both numbers in the ratio must be strictly positive. Zero is not allowed.

Correct: standard ratio with a slash

<div style="aspect-ratio: 16 / 9; width: 100%;"></div>

Correct: single number (height defaults to 1)

<div style="aspect-ratio: 2; width: 100%;"></div>

This is equivalent to aspect-ratio: 2 / 1.

Correct: square ratio

<div style="aspect-ratio: 1 / 1; width: 100%;"></div>

Correct: using the auto keyword

<img src="photo.jpg" alt="A landscape photo" style="aspect-ratio: auto; width: 100%;">

The element uses its intrinsic aspect ratio if available.

Correct: combining auto with a fallback ratio

<img src="photo.jpg" alt="A landscape photo" style="aspect-ratio: auto 4 / 3; width: 100%;">

The browser prefers the image’s intrinsic ratio, but if it hasn’t loaded yet or has no intrinsic ratio, it falls back to 4 / 3. This is useful for preventing layout shift while images load.

Correct: using global CSS values

<div style="aspect-ratio: inherit; width: 100%;"></div>

Global values like inherit, initial, unset, revert, and revert-layer are also valid.