Frame
Aspect-ratio box that locks a child to a fixed ratio. Use for image and media areas that must not shift as content loads.
Frame locks its child to a fixed aspect ratio so the layout reserves the space before the content paints — no shift when an image loads. ratio picks a named preset; customRatio takes any CSS aspect-ratio; fit controls how the child fills the box.
Use it for
- Card and hero image areas that must hold their shape while the image loads
- Video / embed wrappers that need a stable
16-9orcinemabox - Any media slot where a late-loading asset would otherwise cause layout shift
For content that should size to its own intrinsic height, don't wrap it in a Frame — Frame exists to impose a ratio, not follow one.
Import
import { Frame } from '@brikdesigns/bds';Variants
Ratio presets
Named ratios cover the common cases — 1-1 / square, 4-3 (default), 3-2, 16-9 / cinema, photo-landscape, photo-portrait. Prefer a named preset over customRatio when one fits.
<Frame ratio="square">…</Frame>
<Frame ratio="cinema">…</Frame>Custom ratio
When no preset fits, customRatio accepts any CSS aspect-ratio string.
<Frame customRatio="5 / 2">…</Frame>Fit
fit maps to object-fit. cover (default) crops to fill; contain letterboxes to show the whole asset.
<Frame ratio="4-3" fit="contain">…</Frame>When not to use
Frame imposes a ratio — it doesn't read one. If you want an element to keep its natural height, don't wrap it. Frame is for slots whose height must be reserved ahead of content.
- Deprecated mode-words (
portrait,landscape,wide,ultrawide) still resolve but should not be used in new code — reach for the numeric or semantic alias (3-4,4-3,16-9,21-9).
Accessibility
- Renders a plain element (
<div>by default, override withas) withaspect-ratio. It adds no semantics of its own; the child keeps its own role and alt text.
API
| Prop | Type | Default |
|---|---|---|
ratio | FrameRatio | '4-3' |
customRatio | string | — |
fit | FrameFit | 'cover' |
as | ElementType | 'div' |
children | ReactNode | — |
anchor | 'width' | 'height' | 'width' |
Plus all standard HTML attributes for the rendered element. customRatio takes a
CSS aspect-ratio value and overrides ratio when both are set.
FrameRatio carries four deprecated mode-words alongside the ratios and semantic
aliases — portrait, landscape, wide, and ultrawide. They still compile;
use 3-4, 4-3, 16-9, and 21-9 instead.
Related
- Grid — arrange multiple framed cells in a grid
- Storybook playground