---
id: "packages/active-ui/aspect-ratio"
title: "AspectRatio"
description: "A box that keeps a ratio of width to height at any width, for pictures, video and maps."
url: "/packages/active-ui/aspect-ratio"
locale: "en"
revision: "1c96b2e881fcafa9"
---

# AspectRatio

`AspectRatio` keeps a box at a fixed proportion while its width changes: 16:9 for a video, 1:1 for
a tile. The box takes its height from its width, so a picture inside it does not make the page jump
while it loads. It is one `<div>` with the CSS `aspect-ratio` property.

**Example: A 16:9 picture and a square**

Client: Runs entirely in your browser. Source: `examples/ui/aspect-ratio.tsx`.

```tsx
// apps/docs/examples/ui/aspect-ratio.tsx
'use client';

import {AspectRatio} from '@workspace/active-ui/components/primitives/aspect-ratio';

// A picture drawn inline, so the example loads nothing from elsewhere.
const LANDSCAPE =
  'data:image/svg+xml,' +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 90"><rect width="160" height="90" fill="#bfdbfe"/><path d="M0 70 45 35l30 25 25-18 60 48H0z" fill="#3b82f6"/><circle cx="125" cy="22" r="10" fill="#fde68a"/></svg>',
  );

/**
 * A box that keeps a ratio of width to height at any width: a 16:9 picture
 * that fills it, and a square tile. The box reserves its height before the
 * picture loads, so the page does not jump. In an application the picture is
 * usually an `<img>` or `next/image` that fills the box.
 */
export default function AspectRatioExample() {
  return (
    <div className="grid w-full max-w-lg grid-cols-[2fr_1fr] items-start gap-4">
      <AspectRatio ratio={16 / 9} className="overflow-hidden rounded-lg">
        <div
          role="img"
          aria-label="A drawn landscape with hills and a sun"
          className="size-full bg-cover bg-center"
          style={{backgroundImage: `url("${LANDSCAPE}")`}}
        />
      </AspectRatio>
      <AspectRatio
        ratio={1}
        className="bg-muted text-muted-foreground flex items-center justify-center rounded-lg text-sm"
      >
        1 : 1
      </AspectRatio>
    </div>
  );
}
```

## Usage

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

<AspectRatio ratio={16 / 9} className="overflow-hidden rounded-lg">
  <img src={src} alt={alt} className="size-full object-cover" />
</AspectRatio>;
```

## What your application provides

- `ratio`: width divided by height (required), such as `16 / 9`.
- The content, sized to fill the box (`size-full` and `object-cover` for a picture).
- `alt` text for a picture, as always.

## API

**AspectRatio**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `ratio` | `number` | yes | Width divided by height, such as `16 / 9`. |

> [!NOTE]
> **Based on shadcn/ui**
>
> This page adapts the Aspect Ratio documentation of shadcn/ui (MIT licence) to
> this package; see [Third-party notices](/third-party-notices).