/// Layout
AspectRatio
A box that locks its content to a fixed width-to-height ratio.
import { AspectRatio } from "@protocore/pds";Basics
AspectRatio reserves space at a fixed ratio (default 16 / 9) so the layout doesn't reflow while media loads. Images, video and iframes inside fill and cover the box.
16 / 9
Common ratios
Pass any numeric ratio — 1 for square thumbnails, 4 / 3 for diagrams, 21 / 9 for wide banners.
1 / 1
4 / 3
21 / 9
When to use it
Use AspectRatio wherever a media slot must hold its shape before its content has dimensions — thumbnails, cover art, embedded video, chart placeholders, map tiles. It prevents cumulative layout shift: the box claims its height from the ratio, not from the image. It controls shape only — it doesn't crop or bound width, so pair it with a Grid cell or a width-constrained parent. If you just need a plain block with padding, this isn't it; reach for a Card or a styled div.
Usage
Do
- Wrap images, video and iframes so the slot holds its shape while loading.
- Use it inside Grid cells to keep a card wall's media uniform.
- Match the ratio to the source aspect to avoid unwanted cropping.
Don't
- Rely on it to set width — constrain that with the parent (Grid cell, Container).
- Use it for plain text blocks; it locks height to width, which text rarely wants.
- Nest interactive controls whose height must grow with content inside it.
Accessibility
- AspectRatio is a presentational `<div>` and adds no semantics.
- Give the media it wraps its own accessible name (e.g. `alt` on an `<img>`).
AspectRatio props
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Media/content to fit the box (images, video and iframes fill and cover). |
className | string | — | |
ratio | number | 16 / 9 | Width-to-height ratio, e.g. `16 / 9` or `1`. |
style | CSSProperties | — |