# Aspect Ratio

Displays content within a desired ratio, preventing layout shift as media loads.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).





<ComponentThemeTabs>
  <ThemeTab name="mint">
    <PreviewWithCode name="aspect-ratio">
      <div className="w-full max-w-sm">
        <AspectRatio ratio="16 / 9">
          <img src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80" alt="Photo by Drew Beamer" className="h-full w-full rounded-md object-cover" />
        </AspectRatio>
      </div>
    </PreviewWithCode>
  </ThemeTab>

  <ThemeTab name="berries">
    <PreviewWithCode name="aspect-ratio">
      <div className="w-full max-w-sm">
        <AspectRatio ratio="16 / 9">
          <img src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80" alt="Photo by Drew Beamer" className="h-full w-full rounded-md object-cover" />
        </AspectRatio>
      </div>
    </PreviewWithCode>
  </ThemeTab>

  <ThemeTab name="citrine">
    <PreviewWithCode name="aspect-ratio">
      <div className="w-full max-w-sm">
        <AspectRatio ratio="16 / 9">
          <img src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80" alt="Photo by Drew Beamer" className="h-full w-full rounded-md object-cover" />
        </AspectRatio>
      </div>
    </PreviewWithCode>
  </ThemeTab>

  <ThemeTab name="cinnamon">
    <PreviewWithCode name="aspect-ratio">
      <div className="w-full max-w-sm">
        <AspectRatio ratio="16 / 9">
          <img src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80" alt="Photo by Drew Beamer" className="h-full w-full rounded-md object-cover" />
        </AspectRatio>
      </div>
    </PreviewWithCode>
  </ThemeTab>
</ComponentThemeTabs>

## Ratios [#ratios]

Common ratios for different media contexts.

<div className="my-6 grid grid-cols-1 gap-4 sm:grid-cols-3">
  <div>
    <p className="text-muted-foreground mb-2 text-xs">
      1:1 — Square
    </p>

    <AspectRatio ratio="1 / 1" className="bg-muted rounded-md overflow-hidden">
      <img src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80" className="h-full w-full object-cover" />
    </AspectRatio>
  </div>

  <div>
    <p className="text-muted-foreground mb-2 text-xs">
      4:3 — Classic
    </p>

    <AspectRatio ratio="4 / 3" className="bg-muted rounded-md overflow-hidden">
      <img src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80" className="h-full w-full object-cover" />
    </AspectRatio>
  </div>

  <div>
    <p className="text-muted-foreground mb-2 text-xs">
      16:9 — Widescreen
    </p>

    <AspectRatio ratio="16 / 9" className="bg-muted rounded-md overflow-hidden">
      <img src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800&dpr=2&q=80" className="h-full w-full object-cover" />
    </AspectRatio>
  </div>
</div>

## With Placeholder [#with-placeholder]

Use a `bg-muted` background to prevent layout shift while the image loads.

<div className="my-6 w-full max-w-sm">
  <AspectRatio ratio="16 / 9" className="bg-muted rounded-md" />
</div>

## Props [#props]

### AspectRatio [#aspectratio]

| Prop        | Type     | Default | Description                                       |
| ----------- | -------- | ------- | ------------------------------------------------- |
| `ratio`     | `number` | `1`     | Width divided by height — e.g. `16/9`, `4/3`, `1` |
| `className` | `string` | —       | Additional CSS classes                            |

## Usage [#usage]

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

// 16:9 video thumbnail
<AspectRatio ratio={16 / 9}>
  <img src="..." alt="..." className="h-full w-full object-cover" />
</AspectRatio>

// Square avatar
<AspectRatio ratio={1}>
  <img src="..." alt="..." className="h-full w-full rounded-full object-cover" />
</AspectRatio>

// Placeholder while loading
<AspectRatio ratio={16 / 9} className="bg-muted rounded-md" />
```

## Specs [#specs]

```md
# Mint — Aspect Ratio Specs

## Component
- name: aspect-ratio
- file: registry/mint/aspect-ratio.tsx
- installs to: components/ui/aspect-ratio.tsx
- dependencies: radix-ui
- registryDependencies: none

## What is it
A layout utility that enforces a fixed width-to-height ratio on its content.
Use it for images, videos, maps, or any media where you need to prevent layout
shift before the content loads. The ratio is maintained regardless of the
container width. Prefer AspectRatio over manual padding hacks whenever fixed
proportions are required.

## Visual identity
Purely structural — AspectRatio itself carries no colour, radius, or shadow.
Visual character is entirely determined by the child content and any className
passed to the wrapper (e.g. bg-muted, rounded-md).

## Design tokens
No CSS variables consumed directly by the component. Callers typically apply:
--muted: oklch(0.96 0.02 155) / oklch(0.2 0.03 155)   — placeholder background (bg-muted)
--radius: 1.25rem                              — rounded corners (rounded-md on wrapper or child)

## Conventions
- Always set object-cover on img children — object-contain causes letterboxing
- Use bg-muted as a placeholder background while the image is loading
- Wrap in a width-constrained parent (max-w-sm, w-full, etc.) — AspectRatio fills 100% of its container width
- For rounded corners: apply rounded-md and overflow-hidden to the AspectRatio wrapper, or rounded-md directly to the img child
- Do not nest AspectRatio inside flex/grid items without setting explicit widths
- Sub-components expose data-slot="aspect-ratio" for CSS targeting
```

## Installation [#installation]

<CommandBox componentName="aspect-ratio" className="mt-2" />