# AspectRatio

> A box held to a width-to-height ratio, so media keeps its shape and never shifts the layout while loading.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/aspect-ratio

## Installation

```bash
npx shadcn@latest add KezLahd/rime/aspect-ratio
```

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.

## Usage

```tsx
import { AspectRatio } from "@/components/ui";

<AspectRatio ratio={16 / 9}>
  <img src="/cover.jpg" alt="The new office, from the street" />
</AspectRatio>
```

## Props: 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.

## Examples

### 16 / 9

```tsx
<AspectRatio ratio={16 / 9}>…</AspectRatio>
```

### Square and 4 / 3

```tsx
<AspectRatio ratio={1}>…</AspectRatio>
<AspectRatio ratio={4 / 3}>…</AspectRatio>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--aspect-radius` | `var(--inner-radius, var(--r-lg))` |
| `--aspect-ratio` | `1.7778` |
| `--aspect-width` | `100%` |
| `--inner-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--line`, `--r-lg`, `--surface-sunken`.

## Accessibility

- A plain box with no role; give the media inside it its own alt text or captions.

## 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.

Related: https://rime.mjsons.net/components/carousel