# Aspect Ratio

Holds an image or video at a fixed ratio, so layouts never jump while media loads.

Tier: Free

## Installation

```bash
npx shadcn add @fetaui/aspect-ratio
```

## Usage

```tsx
import { AspectRatio } from '@/components/fetaui/aspect-ratio'

export function Example() {
  return <AspectRatio ratio="3:2" src="/dunes.jpg" alt="Dunes at golden hour" caption="Golden hour over the dunes" />
}
```

## API

| Prop | Type | Default |
|---|---|---|
| ratio | 1:1, 4:3, 3:2, 16:9, 21:9, 9:16 | 16:9 |
| src | string |  |
| alt | string | '' |
| content | image, video, loading, empty, error | follows src |
| children | ReactNode |  |
| caption | ReactNode |  |
| duration | string |  |
| onPlay | () => void |  |
| onFile | (file) => void |  |
| uploading | boolean | false |
| accept | string | image/png,image/jpeg |
| emptyTitle, emptyHint | string |  |
| errorTitle, errorHint | string |  |
| onRetry | () => void |  |
| animated | boolean | true |

## When to use

- Around every image and video, so space is reserved before it loads.
- Pick the ratio from the content, not the container.

## When not to use

- For media that must keep its own shape: use a plain image with width and height.

## Accessibility

- Always give images alt text. The caption is visible, alt is for screen readers.
- Play is a real button named Play video with the duration.
- Errors are announced as they appear.

## Motion

- A band sweeps the frame every 1400 ms while loading, and pauses off screen.
- Loaded media fades, sharpens from 8 px and settles from 1.02 in 320 ms. The frame never resizes.
- Dragging over Empty inks the ring and fill in 150 ms.
- With reduced motion, Loading holds a still 5% fill and media fades in 120 ms.