Layout

Aspect ratio

Locks its content to a fixed aspect ratio and clips overflow for framing media at a consistent shape.

Install

npx shadcn@latest add @alix/aspectRatio

Preview

Usage

<AspectRatio ratio="16/9">
  <img src="/media/grey-arc.svg" alt="" className="size-full object-cover" />
</AspectRatio>

Examples

The ratio vocabulary

The same media, framed to different Figma ratio tokens — the shape is the design decision, the media just fills it.

1/1

4/3

16/9

{(["1/1", "4/3", "16/9"] as const).map((ratio) => (
  <AspectRatio key={ratio} ratio={ratio}>
    <img src="/media/grey-arc.svg" alt="" className="size-full object-cover" />
  </AspectRatio>
))}

Portrait framing

Tall ratios for a headshot or a standing editorial image — the frame clips overflow so the crop is consistent.

3/4

9/16

<AspectRatio ratio="3/4">
  <img src="/media/grey-arc.svg" alt="" className="size-full object-cover" />
</AspectRatio>
<AspectRatio ratio="9/16">
  <img src="/media/grey-arc.svg" alt="" className="size-full object-cover" />
</AspectRatio>

A uniform media grid

Dropped into each Grid cell, it holds every thumbnail to one shape so the row reads evenly regardless of the source images.

<Grid columns={3} gap="sm">
  {[0, 1, 2].map((i) => (
    <AspectRatio key={i} ratio="4/3">
      <img src="/media/grey-arc.svg" alt="" className="size-full object-cover" />
    </AspectRatio>
  ))}
</Grid>

When to use it

Use it for

Framing media to a fixed shape when the ratio is chosen at runtime — a CMS field or block prop that Tailwind's build-time aspect-[x/y] can't express.
Holding a grid of thumbnails to one uniform shape so a row of mixed source images reads evenly.
Any image, video, or iframe that must crop to a consistent frame — the child keeps its own alt, loading, and srcSet.

Reach for something else

A full-bleed strip that must stay a set height while the width flexes — use MediaBanner.
A build-time-constant ratio with no runtime input — a plain aspect-video overflow-hidden div is lighter.
Capping content width — that is Container, not a media frame.

Props

Prop	Type	Default	Description
ratio	AspectRatioToken \| (string & {}) \| number	"16/9"	The aspect ratio, applied via inline style so any runtime value works. Use a Figma token (e.g. "4/3", "21/9"), an arbitrary string, or a number.
children	ReactNode	—	The media slot — pass a real <img>, <video>, <iframe>, or Next <Image fill>. Give the child size-full object-cover to fill the frame.