A box held to a width-to-height ratio, so media keeps its shape and never shifts the layout while loading.
AspectRatio sizes itself from its width and a ratio (16 / 9 by default) with the CSS aspect-ratio property. A direct <img>, <video>, <iframe> or <picture> child fills it with object-fit: cover. framed (on by default) clips it to the inner radius on a sunken fill with a hairline, so an empty or loading box still reads as a frame.
Installation
npx shadcn@latest add KezLahd/rime/aspect-ratioAlso installs: base.
Usage
import { AspectRatio } from "@/components/ui";
<AspectRatio ratio={16 / 9}>
<img src="/cover.jpg" alt="The new office, from the street" />
</AspectRatio>Examples
16 / 9
Square and 4 / 3
API
Generated from the component's TypeScript types and JSDoc (scripts/gen-ui-registry.mjs), so it always matches the source.
AspectRatio
| Prop | Type | Default | Description |
|---|---|---|---|
| ratio | number | 16 / 9 | Width over height: 16 / 9, 4 / 3, 1. Default 16 / 9. |
| framed | boolean | true | Rounded, clipped frame with a hairline, for media on a panel. Default true. |
Also accepts the native attributes of AriaAttributes, DOMAttributes, HTMLAttributes.
Theme tokens
Per-component tokens are undeclared by default, so the default shown is the fallback the CSS uses. Set one at :root (or in theme.css) to restyle every instance. Live values are read from this page, so they follow the Rime Studio.
| Token | Default | Live value |
|---|---|---|
| --aspect-radius | var(--inner-radius, var(--r-lg)) | … |
| --aspect-ratio | 1.7778 | … |
| --aspect-width | 100% | … |
| --inner-radius | var(--r-lg) | … |
System tokens it reads
| Token | Default | Live value |
|---|---|---|
| --border-w | tokens.css | … |
| --line | tokens.css | … |
| --r-lg | tokens.css | … |
| --surface-sunken | tokens.css | … |
Accessibility
- A plain box with no role; give the media inside it its own alt text or captions.
Do and don't
Do
- Use it for every image whose size is not known ahead, so nothing jumps when it loads.
Don't
- Don't crop faces or text with cover; pick a ratio that suits the media.
For AI agents
This page as markdown, rendered from the same registry entry. Point an agent at it (or add .md to this page's URL), or at /llms.txt for the index.
Open aspect-ratio.mdRelated: carousel