Skip to content
Component installs need the registry setup
VegaStack Design

Aspect Ratio

Constrains its children to a desired width-to-height ratio — widescreen media, square thumbnails, or portrait crops.

Status
stable
Since
0.10.0
Accessibility pattern
presentational wrapper

Last updated

A scenic landscape

Install

Configure registry credentials first using the Quickstart. Before copying this item or any transitive registry dependency, verify the signed manifest and save the exact bytes for Aspect Ratio before installation. Retain the digest printed by this command.

pnpm exec vegastack-design verify aspect-ratio

Install with the pinned shadcn CLI. Bare shadcn does not verify VegaStack signature or integrity.

pnpm dlx shadcn@4.21.0 add @vegastack/aspect-ratio

Run the exact offline --post-write command printed by the preflight, using its saved item path and independently retained --expected-integrity digest. Use the saved preflight for every transitive registry dependency too; stop on any mismatch before using the components.

Usage

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

<AspectRatio ratio={16 / 9}>
  <img
    src="/photo.jpg"
    alt="Photo"
    className="absolute inset-0 size-full object-cover"
  />
</AspectRatio>;
A scenic landscape

Examples

Square

A square aspect ratio using ratio={1 / 1}. Useful for displaying images in a square format.

A scenic landscape

Portrait

A portrait aspect ratio using ratio={9 / 16}. Useful for displaying images in a portrait format.

A scenic landscape

RTL

The box reserves space with aspect-ratio and a CSS custom property, neither of which has a writing direction — so a right-to-left document gets the identical geometry, and only the surrounding caption and content flow mirror.

A scenic landscape
Beautiful landscape
منظر طبيعي جميل
منظر طبيعي جميل

API Reference

PropTypeDefaultDescription
ratio*number—

Accessibility

  • AspectRatio renders a plain <div> and contributes nothing to the accessibility tree — it is geometry, not semantics.
  • The accessible name belongs to the child. Give a meaningful image an alt, and a decorative one alt="" so a screen reader skips it.
  • The element is position: relative, so a filling child is positioned with absolute inset-0 rather than being stretched by the wrapper — nothing is clipped out of the reading order.
ContractStates tested
Behaviourdefault
Accessibilitynative-or-base-ui-semantics, browser-accessibility-test
Visualdefault

Do / Don't

Do
Pass the ratio as an expression — ratio={16 / 9} — so the intent stays readable.
Don't
Set a fixed height on the wrapper; that is the one thing the ratio is there to compute.

Deviations

Upstream's file plus packages/ui/upstream/patches/aspect-ratio.patch. Every hunk:

  • DOC-2 — cn is imported from @vegastack/design.

Direction

The text-direction context every component reads for its logical-property layout — a provider and the hook that resolves it.

Board

Kanban columns over the drag-reorder seam — pointer drag, keyboard move mode, a per-card actions menu, server-refusable moves, collapsed lanes.

On this page

InstallUsageExamplesSquarePortraitRTLAPI ReferenceAccessibilityDo / Don'tDeviations