Aspect Ratio

Constrains child content to a given aspect ratio using Radix UI. Ideal for images, videos, and responsive media containers.

Basic

Constrains child content to a specified aspect ratio, preventing layout shift for images, videos, and embedded media.

16:9

<AspectRatio ratio={16 / 9}>
<img src="/hero.jpg" alt="Hero" className="object-cover w-full h-full" />
</AspectRatio>

<AspectRatio ratio={16 / 9}><img src="/hero.jpg" alt="Hero" className="object-cover w-full h-full" /></AspectRatio>

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add aspect-ratio

pnpm dlx @work-rjkashyap/unified-ui add aspect-ratio

npx @work-rjkashyap/unified-ui add aspect-ratio

bunx @work-rjkashyap/unified-ui add aspect-ratio

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { AspectRatio } from "@work-rjkashyap/unified-ui";

Basic Usage

Wrap any content in AspectRatio to constrain it to a specific ratio. The component uses Radix UI's AspectRatio primitive under the hood.

<AspectRatio ratio={16 / 9}>
  <img src="/photo.jpg" alt="Landscape" className="object-cover w-full h-full rounded-lg" />
</AspectRatio>

Common Ratios

1:1

Square

4:3

Classic

16:9

Widescreen

<AspectRatio ratio={1}>...</AspectRatio>      {/* Square */}
<AspectRatio ratio={4 / 3}>...</AspectRatio>  {/* Classic */}
<AspectRatio ratio={16 / 9}>...</AspectRatio> {/* Widescreen */}

<AspectRatio ratio={1}>...</AspectRatio>      {/* Square */}<AspectRatio ratio={4 / 3}>...</AspectRatio>  {/* Classic */}<AspectRatio ratio={16 / 9}>...</AspectRatio> {/* Widescreen */}

Ratio	Value	Use Case
`1:1`	`1`	Avatars, thumbnails, album art
`4:3`	`4 / 3`	Classic photos, presentations
`16:9`	`16 / 9`	Video, hero images, widescreen
`21:9`	`21 / 9`	Ultra-wide, cinematic banners
`3:2`	`3 / 2`	Photography, print media
`2:3`	`2 / 3`	Portrait photos, book covers

With Images

<AspectRatio ratio={16 / 9}>
  <img
    src="/landscape.jpg"
    alt="Mountain landscape"
    className="object-cover w-full h-full rounded-lg"
  />
</AspectRatio>

With Video

<AspectRatio ratio={16 / 9}>
  <iframe
    src="https://www.youtube.com/embed/..."
    title="Video"
    className="w-full h-full rounded-lg"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope"
    allowFullScreen
  />
</AspectRatio>

With Map or Embed

<AspectRatio ratio={4 / 3}>
  <iframe
    src="https://maps.google.com/..."
    title="Map"
    className="w-full h-full rounded-lg border-0"
  />
</AspectRatio>

Responsive Card Image

A common pattern is combining AspectRatio with Card for consistent media cards:

<Card>
  <AspectRatio ratio={16 / 9}>
    <img
      src="/card-image.jpg"
      alt="Card preview"
      className="object-cover w-full h-full"
    />
  </AspectRatio>
  <CardBody>
    <Heading level={3}>Card Title</Heading>
    <Body>Description text goes here.</Body>
  </CardBody>
</Card>

Props

Prop	Type	Default	Description
`ratio`	`number`	`1`	The desired width-to-height ratio (e.g. `16 / 9`).
`className`	`string`	—	Additional CSS classes on the wrapper element.
`children`	`React.ReactNode`	—	Content to render inside the aspect ratio container.

All standard <div> HTML attributes are also forwarded to the underlying element.

Accessibility

The component renders a semantic <div> with position: relative — assistive technologies treat it as a plain container.
Always provide alt text on <img> children and title on <iframe> children.
The component does not trap focus or alter tab order.

Design Tokens

Token	Usage
`--radius-*`	Border radius on the container

On this page