The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Set a preferred ratio | .card { aspect-ratio: 16 / 9; } | View examples |
| Create a square | .avatar { inline-size: 4rem; aspect-ratio: 1; } | View examples |
| Use natural ratio when present | .media { aspect-ratio: auto; } | View examples |
| Fallback until media loads | img { aspect-ratio: auto 4 / 3; } | View examples |
| Declare intrinsic image dimensions | <img src="chart.png" width="1200" height="800" alt="Quarterly revenue chart"> | View examples |
| Scale media responsively | img { max-inline-size: 100%; block-size: auto; } | View examples |
| Fill and crop a media box | .thumb {
inline-size: 100%;
aspect-ratio: 3 / 2;
object-fit: cover;
} | View examples |
| Fit without cropping | .diagram {
inline-size: 100%;
aspect-ratio: 16 / 9;
object-fit: contain;
} | View examples |
| Move the crop focal point | .portrait {
object-fit: cover;
object-position: 50% 20%;
} | View examples |
| Apply ratio to the border box | .tile {
box-sizing: border-box;
inline-size: 18rem;
aspect-ratio: 1;
padding: 1rem;
} | View examples |
| Bound a ratio box | .preview {
inline-size: 100%;
max-block-size: 70vh;
aspect-ratio: 16 / 9;
} | View examples |
| Use ratio in responsive grid | .grid {
grid-template-columns:
repeat(auto-fit, minmax(min(100%, 15rem), 1fr));
} | View examples |
| Let a ratio item shrink | .media {
flex: 1 1 18rem;
min-inline-size: 0;
aspect-ratio: 4 / 3;
} | View examples |
| Size a responsive iframe | .embed {
inline-size: 100%;
aspect-ratio: 16 / 9;
border: 0;
} | View examples |
| Provide a legacy ratio box | .frame {
position: relative;
padding-block-start: 56.25%;
} | View examples |
| Keep dimensions with lazy loading | <img src="photo.jpg" width="800" height="600" loading="lazy" alt="Forest trail at dawn"> | View examples |
| Avoid cropping meaningful diagrams | .diagram { object-fit: contain; background: Canvas; } | View examples |
| Use logical width constraints | .figure {
inline-size: min(100%, 32rem);
aspect-ratio: 3 / 2;
} | View examples |
aspect-ratio supplies a preferred width-to-height relationship used by automatic sizing. Images, video, iframes, and other replaced elements add natural dimensions and sometimes a natural ratio, so the result depends on whether one axis is automatic, which box is measured, and which constraints win. This guide builds stable responsive media without cropping important content or causing layout shifts.
Step by step
Detailed examples
Treat the ratio as a sizing preference
aspect-ratio defines a preferred ratio, not an unconditional lock. It affects automatic sizes and some layout calculations only when at least one axis behaves as auto; explicitly setting both width and height leaves nothing for the ratio to derive. A ratio of 16/9 means width divided by height. Degenerate ratios behave as auto. Padding, borders, and box-sizing determine which box participates for an explicit ratio.
.video-card { inline-size: min(100%, 40rem); block-size: auto; aspect-ratio: 16 / 9; }Combine authored and natural dimensions correctly
A replaced element such as img may have a natural width, height, and ratio from its resource. auto preserves that natural ratio. The combined auto <ratio> form supplies the authored ratio until intrinsic information becomes available, then uses the natural ratio. HTML width and height attributes let the browser calculate an image ratio before download and are usually the best layout-shift defense; CSS can still make the image responsive.
<img src="team.webp" width="1200" height="800" alt="The support team in the workshop">img { display: block; max-inline-size: 100%; block-size: auto; }Control content inside a fixed media box
object-fit changes how replaced content is fitted into its content box; it does not size the box itself. cover fills and crops, contain fits the complete source and can letterbox, fill distorts, none keeps natural sizing, and scale-down chooses the smaller result of none or contain. object-position controls alignment of the source. Avoid cover for diagrams, text screenshots, QR codes, or other content whose edges carry meaning.
.thumb { inline-size: 100%; aspect-ratio: 3 / 2; object-fit: cover; object-position: 50% 25%; }Expect min and max constraints to win
The preferred ratio participates in sizing, then min-width, max-width, min-height, max-height, content minimums, and available space can override it. With box-sizing:border-box, an explicitly supplied ratio is applied to border-box dimensions; auto ratios from replaced elements use content-box dimensions. Use overflow policies intentionally when content inside a non-replaced ratio box needs more height than the preferred shape.
.promo { box-sizing: border-box; inline-size: min(100%, 24rem); min-block-size: 12rem; aspect-ratio: 2 / 1; overflow-wrap: anywhere; }Account for grid and flex automatic sizing
A definite grid track or flexed inline size can provide the axis from which the ratio calculates the other dimension. Automatic minimum sizes can still prevent shrinking; use min-inline-size:0 or minmax(0,1fr) only when an explicit wrap or overflow strategy exists. In grids, tall content can expand a row beyond the preferred ratio. A non-replaced box with aspect-ratio does not become a replaced element and retains its normal alignment behavior.
.gallery { display: grid; grid-template-columns: repeat(auto-fit,minmax(min(100%,16rem),1fr)); gap: 1rem; }
.gallery figure { margin: 0; }
.gallery img { inline-size: 100%; aspect-ratio: 4 / 3; object-fit: cover; }Progressively enhance responsive embeds
An iframe often has no useful natural ratio. Give it a width and aspect-ratio, remove its default border if appropriate, and retain a title that names the embedded content. For old engines, a wrapper with percentage block-start padding can reserve space because percentage padding resolves against inline size; then override that technique inside @supports to avoid two competing sizing systems.
<iframe class="embed" src="/report" title="Interactive quarterly report" loading="lazy"></iframe>.embed { inline-size: 100%; block-size: 22.5rem; }
@supports (aspect-ratio: 16 / 9) { .embed { block-size: auto; aspect-ratio: 16 / 9; } }Reserve space without hiding information
Stable dimensions reduce cumulative layout shift, but a placeholder ratio must approximate the eventual media or the box will still change when auto switches to the natural ratio. Lazy loading does not replace width and height. Supply meaningful alt text, empty alt for decorative images, iframe titles, and captions where needed. Test zoom and text spacing: fixed-ratio containers holding live text should usually use min-block-size rather than fixed block-size so content can grow.
.text-card { min-block-size: 12rem; aspect-ratio: 2 / 1; }
.info-graphic { inline-size: 100%; block-size: auto; object-fit: contain; }Local code tester
Compare cover, contain, and natural media sizing
Switch the fit mode to see how a fixed-ratio box crops or letterboxes the same accessible image.
Sources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.