AspectRatio
Constrains content to a fixed width-to-height ratio
Category: layout · WCAG 2.2-AA · layout, ratio, image, video, responsive
Props
| Prop | Type | Default | Description |
|---|---|---|---|
ratio | number | 16 / 9 | Width-to-height ratio applied via the CSS aspect-ratio property |
children | ReactNode | — | Content to fill the ratio box (typically an image, video, or iframe) |
Design tokens
--cascivo-aspect-ratio
When to use
- Reserving a stable box for media that loads asynchronously, avoiding layout shift
- Embedding responsive iframes (video, maps) at a known proportion
- Keeping thumbnails or covers uniform across a grid
When not to use
- Content whose height should grow with text — let it size naturally
- A single fixed-pixel image where width and height are already known
How to build an accessible AspectRatio in React →
Examples
Image at 16:9
<AspectRatio ratio={16 / 9}>
<img src="/cover.jpg" alt="Cover" />
</AspectRatio>Square
<AspectRatio ratio={1}>
<img src="/avatar.jpg" alt="Avatar" />
</AspectRatio>Related components
- Card — Commonly holds a cover image inside a Card media region