Images compose the same way borders do: sets the fill behaviour, and an aspect-ratio class locks the shape. The pair together means a layout holds its geometry before the file has loaded, so nothing reflows as images arrive.
The base class
on its own fills the width of its container and keeps its natural proportions.
| Property | Value | Why |
|---|---|---|
display |
block |
Removes the baseline gap an inline image leaves beneath it |
width |
100% |
Fills the container rather than rendering at intrinsic size |
height |
auto |
Keeps the natural ratio when no aspect class is applied |
object-fit |
cover |
Fills the box and crops the overflow, so an aspect class never distorts the picture |
<img class="img" src="/assets/images/og-default.png" alt="…">
Aspect ratios
Add one ratio class to lock the shape. Because object-fit is cover, the image crops to fill rather than stretching — the subject stays in proportion at every ratio.
.img-1x1 — square, for an avatar or a topic tile
.img-4x3 — the classic photograph
.img-3x2 — a wider editorial crop
.img-16x9 — video, and the share card
.img-21x9 — a cinematic banner
<img class="img img-16x9" src="/assets/images/og-default.png" alt="…">
| Class | Ratio | Suits |
|---|---|---|
| 1 : 1 | Avatars, topic tiles, anything in a grid where the shape should be uniform | |
| 4 : 3 | A standard photograph, and the safest default for supplied imagery | |
| 3 : 2 | An editorial crop with a little more width | |
| 16 : 9 | Video thumbnails and the share card | |
| 21 : 9 | A banner, where the image is a band rather than a picture |
Rules
- Always pair a ratio with . The ratio class sets shape and nothing else; without the base class there is no
object-fit, and the picture distorts to fill the box. - Never set width or height on the element. The class owns both; an attribute or inline size fights it and reintroduces the reflow the ratio exists to prevent.
- Write real
alttext, or an empty one deliberately.alt=""tells a screen reader to skip a decorative image, which is correct; a missingaltmakes it read the filename. - Choose the ratio for the content, not the layout. A face cropped to 21:9 loses the face; if the band is what the layout needs, the image should be one that survives it.