Skip to content
garn

Aspect Ratio

Constrains content to a fixed width:height ratio that scales with its container.

Stablev0.4.2added in v0.1.0@garn/ui/aspect-ratio
On this page

Default

A 16:9 media box.

16 / 9

Installation

garn is copy-in — the garn CLI writes this component's source into your project, so you own and can edit it. It resolves any base files and installs the npm dependencies below for you.

terminal
npx garn-ui add aspect-ratio
First time? Set up garn in your project
Registry
aspect-ratio
Deps
@radix-ui/react-aspect-ratio
Registry deps
None — standalone

Import

import { AspectRatio } from "@garn/ui/aspect-ratio";

Props

The component's public props and their types.

No component-specific props — this is a thin wrapper over its native element.

Styling

Target these data-slots and states, and remap these tokens, to restyle without forking the component.

[data-slot="aspect-ratio"]

When to use

Constrain media (image, video, embed, map) to a fixed width:height ratio that scales with its container.

Reach for something else when

  • A box whose height should follow its content (just let it flow)
  • a single fixed pixel size (set width/height directly).

Overview

AspectRatio constrains media — an image, video, embed, or map — to a fixed width:height ratio that scales with its container, so the box reserves its space before the content loads and never reflows. Give it a ratio (16/9, 1, 4/3) and drop the media inside. It's a layout primitive for ratio-locked media; for free-flowing content use normal sizing, and to clip a too-tall element use overflow instead.

Guidelines

Use it to prevent layout shift on media. Wrapping an image/video in a locked ratio reserves the slot up front, so the page doesn't jump when it loads — the main reason to reach for it. Pick the ratio that matches the asset's native shape to avoid letterboxing.

Let the media fill, and crop deliberately. Have the child cover the box (object-fit) so it fills without distortion, and accept that covering crops — frame the asset so the important part survives. Don't stretch content to a ratio it wasn't made for.

Keep accessibility on the media, not the wrapper. The ratio box is purely presentational; put alt text on the image and captions/labels on the video. Reserve it for genuinely ratio-bound content rather than as a generic spacer.

Best practices

Do
  • Give the AspectRatio a width (or let it fill its container) — the height is computed from ratio.
  • Use it for responsive media so it reserves space and avoids layout shift.
Don't
  • Don't set an explicit height on the child — the ratio computes it.
  • Don't wrap text whose height should grow naturally.

Content guidelines

  • AspectRatio has no text of its own — put the accessible name on the media child (img alt, iframe title).

Accessibility

A1.1.1Non-text Content
  • AspectRatio is presentational — it adds no role. The semantics belong to the child (e.g. an <img> needs `alt`).