Components

Aspect Ratio

Constrains its content to a fixed width-to-height ratio, keeping images, video, and embeds from shifting layout as they load.

Basic usage

Wrap any element and pass a ratio. The child fills the box at all widths — give it h-full w-full. Rounding and clipping belong on AspectRatio itself, because its className lands on the box the child sits in.

Common ratios

Any numeric ratio works — square, classic photo, and widescreen are the most common. These placeholders are painted with role tokens (muted, secondary, accent) and their matching foregrounds, so they stay legible in the high-contrast palette too.

1 / 1

4 / 3

16 / 9

Props

Prop	Type	Default	Description
`ratio`	number	`1`	Desired width-to-height ratio, expressed as a number (e.g. 16 / 9). The box is sized by a padding-bottom of 100 / ratio percent.
`children`required	React.ReactNode	`—`	The content to constrain — typically an img, video, or iframe. Give it h-full w-full so it fills the box.
`asChild`	boolean	`false`	Radix Slot escape hatch — apply the ratio box to your own element instead of rendering a div.
`className`	string	`—`	Merged onto the inner, absolutely-positioned box — not the outer padding wrapper. Put overflow-hidden and rounded-* here.
`style`	React.CSSProperties	`—`	Merged onto the same inner box, but position and the four inset values are always overwritten to keep the ratio maths working.
`...rest`	React.ComponentProps<'div'>	`—`	All native div props are forwarded to the inner box.

Accessibility

Aspect Ratio is a purely presentational wrapper — it adds no roles or ARIA and never traps focus.
Reserving space ahead of load prevents content from jumping, which reduces cumulative layout shift and is friendlier to users with motion sensitivity.
Always provide a meaningful alt on wrapped images, or an accessible title on embedded iframes and video.
Nothing clips by default — pass overflow-hidden rounded-* to AspectRatio, which puts them on the inner box so the child is clipped to the rounded corners.