Ratio
Keep an element at a fixed aspect ratio while it scales with its container. Ratio
is built for responsive media — an <iframe>, <video>,
<img>, or map — that must not jump around as the page reflows. The child
fills the box; the box keeps the shape.
Import
import { Ratio } from '@metatoy/bootstrap-styled';Named ratios
Pass one of the four presets to ratio: '1x1' (the default), '4x3', '16x9', or
'21x9'. The box holds that proportion no matter how wide its parent gets.
Embedding media
Whatever you nest inside a Ratio is stretched to fill it, so a video or embed becomes
responsive with no extra styling. Constrain the width with your layout and the height
follows the ratio.
Custom ratios
For a shape outside the presets, pass a padding-top percentage string — height ÷ width.
'50%' gives a 2×1 box, '75%' a 4×3, '100%' a square. The value maps straight onto the
--bs-aspect-ratio custom property.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| ratio | RatioName | string | — | A preset aspect ratio (`'1x1' | '4x3' | '16x9' | '21x9'`) or a custom `padding-top` percentage string (e.g. `'50%'` for 2x1). Defaults to `'1x1'`. A custom value maps straight onto `--bs-aspect-ratio`. |
| as | React.ElementType | — | — |
Ratio also accepts all native <div> attributes and an as prop.
Theming
Ratio works entirely through the --bs-aspect-ratio custom property: the named presets
resolve to their percentage (1x1 → 100%, 4x3 → 75%, 16x9 → 56.25%, 21x9
→ ≈42.857%) and a custom string is written straight through. It sets no color of its own —
the appearance comes from the child you place inside. You can set --bs-aspect-ratio in a
scope to drive the ratio from CSS instead of the prop.
Accessibility
Ratio is a presentational wrapper and adds no semantics. The accessible name and role
belong to the child: give an <iframe> a meaningful title, an <img> an alt, and a
<video> its captions and controls. The ratio box only governs the dimensions, never the
meaning.