---
title: Aspect Ratio
description: Constrains content to a desired width-to-height ratio.
icon: rectangle-horizontal
author:
  name: shadcn
  url: https://github.com/shadcn
mode: wide
---

<PoweredBy packages={[{ name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/aspect-ratio' }]} />

### Installation

```package-install
npx shadcn@latest add @redpanda/aspect-ratio
```

<ComponentPreview name="aspect-ratio-demo" />

## When to use

Use AspectRatio when content (images, video embeds, maps, placeholders) must keep a fixed proportion regardless of the container width. The component reserves the correct height up front, which prevents layout shift while media loads.

## Usage

```tsx
import { AspectRatio } from '@/components/redpanda-ui/aspect-ratio';
```

```tsx
<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-lg bg-surface-subtle">
  <img alt="Photo of a redpanda" className="h-full w-full object-cover" src="/images/redpanda.jpg" />
</AspectRatio>
```

## Anatomy

The AspectRatio component is a plain container styled with the CSS `aspect-ratio` property:

```
AspectRatio
├── Base element (div, relative positioning)
├── --ratio custom property - set from the ratio prop
├── aspect-(--ratio) - CSS aspect-ratio driven sizing
└── children - fill the box (use h-full w-full or absolute inset-0)
```

The container is `relative`, so children can use `absolute inset-0` (or `h-full w-full`) to fill it. Add `overflow-hidden` plus a radius on the AspectRatio itself when clipping media to rounded corners.

## Examples

### Common Ratios

<ComponentPreview
  name="aspect-ratio-ratios-demo"
  description="Square (1:1), standard (4:3), and widescreen (16:9) containers side by side."
/>

```tsx
<AspectRatio ratio={1}>{/* square */}</AspectRatio>
<AspectRatio ratio={4 / 3}>{/* standard */}</AspectRatio>
<AspectRatio ratio={16 / 9}>{/* widescreen */}</AspectRatio>
```

## Props

| Prop        | Type     | Default | Description                                            |
| ----------- | -------- | ------- | ------------------------------------------------------ |
| `ratio`     | `number` | —       | Width-to-height ratio of the container (e.g. `16 / 9`) |
| `className` | `string` | —       | Additional CSS classes                                 |
| `testId`    | `string` | —       | Value applied to `data-testid` for testing             |

All other props are forwarded to the underlying `div` element.

## Accessibility

- AspectRatio is purely presentational and adds no semantics or keyboard interactions.
- Provide meaningful `alt` text on images rendered inside the container.

## Credits

- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/aspect-ratio) for the aspect ratio component.