Aspect ratio
An aspect ratio box keeps a set proportion and makes its child fill it, so media takes its space before it loads and the page doesn't jump.
<tk-aspect-ratio ratio="16/9" style="max-inline-size: 320px"> <tk-skeleton shape="rect"></tk-skeleton> </tk-aspect-ratio>
Anatomy
| Part | What it is |
|---|---|
tk-aspect-ratio |
the box; draws nothing and clips what overflows |
| default slot | one direct child, which fills the box |
Ratios
<div style="display: flex; gap: var(--space-16); align-items: start"> <tk-aspect-ratio ratio="1/1" style="inline-size: 96px"><tk-skeleton shape="rect"></tk-skeleton></tk-aspect-ratio> <tk-aspect-ratio ratio="16/9" style="inline-size: 96px"><tk-skeleton shape="rect"></tk-skeleton></tk-aspect-ratio> <tk-aspect-ratio ratio="4/3" style="inline-size: 96px"><tk-skeleton shape="rect"></tk-skeleton></tk-aspect-ratio> <tk-aspect-ratio ratio="3/4" style="inline-size: 96px"><tk-skeleton shape="rect"></tk-skeleton></tk-aspect-ratio> <tk-aspect-ratio ratio="3/2" style="inline-size: 96px"><tk-skeleton shape="rect"></tk-skeleton></tk-aspect-ratio> </div>
ratio |
Typical use |
|---|---|
1/1 |
avatars, thumbnails, tiles |
16/9 (default) |
hero media, video, cards |
4/3 |
classic photos |
3/4 |
vertical cards, cover art |
3/2 |
editorial photos |
An unknown value falls back to 16/9.
Other ratios
For a ratio outside the set, such as 21:9 or 9:16, set --tk-aspect-ratio to a CSS
aspect-ratio value. It overrides ratio.
<tk-aspect-ratio style="--tk-aspect-ratio: 21 / 9; max-inline-size: 320px"> <tk-skeleton shape="rect"></tk-skeleton> </tk-aspect-ratio>
Size and fill
Set the box's width, such as with a column, a grid cell, or max-inline-size. The height
follows from the ratio. A height you set yourself overrides the ratio.
The child fills the box with no class or wrapper. It must be a direct child: a child
inside a wrapper <div> keeps its own size and doesn't fill.
<tk-aspect-ratio ratio="16/9"> <tk-image src="/photos/skyline.jpg" alt="A city skyline at dusk"></tk-image> </tk-aspect-ratio>
To round or clip the media, style the child, or use --tk-image-radius on
When to use
- Use it around media, such as an
Image , a video, a map, or an embed, so its space is reserved before it loads. - Use it for any single child that should keep a proportion, such as a
Skeleton or a colored panel. - Use plain CSS
aspect-ratiofor a one-off outside your media. - It isn't an image (no
srcoralt; useImage ) and isn't a layout grid.
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Wrap media to reserve its space | Let the page jump when an image loads |
| Put the child directly inside | Wrap the child in a <div> |
Use --tk-aspect-ratio for a ratio outside the set |
Stretch a named ratio with a fixed height |
| Round the corners on the child | Expect the box to draw a frame |
Related
Image : the image this reserves space for.Skeleton : a placeholder that fills the box while content loads.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
ratio |
16/9 | 1/1 | 4/3 | 3/4 | 3/2 |
16/9 |
the box proportion; an unknown value falls back to 16/9 |
Slots
| Slot | Content |
|---|---|
| default | one element that fills the box |
Events
None.
CSS
--tk-aspect-ratio: any CSSaspect-ratiovalue, such as21 / 9; it overridesratio.
Tokens
ratio |
Token |
|---|---|
1/1 |
aspect-ratio/1-1 |
16/9 |
aspect-ratio/16-9 |
4/3 |
aspect-ratio/4-3 |
3/4 |
aspect-ratio/3-4 |
3/2 |
aspect-ratio/3-2 |
More in
Accessibility
The box adds nothing for assistive technology: no role, no name, no focus. All meaning
is on the child, such as the image's alt.