caliper uidocs
DemoSign inGet Pro

Aspect ratio

Free

A box that keeps a fixed ratio so images and video never shift the layout.

Installs components/ui/aspect-ratio.tsxDepends on none beyond ReactMotion shared motion tokens
pnpm dlx shadcn@latest add https://caliperui.site/r/aspect-ratio.json
16:9

When to use #

Use it for

  • Thumbnails, covers and embedded video.
  • Skeletons that must match final media size.

Skip it when

  • Content that should size itself.

Installation #

terminal
pnpm dlx shadcn@latest add https://caliperui.site/r/aspect-ratio.json

Adds its 2 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above. It is built from AspectRatio and AspectRatioImage.

example.tsx
import { AspectRatio } from "@/components/ui/aspect-ratio"

export function WideBox() {
  return (
    <div className="w-full max-w-sm">
      <AspectRatio ratio={16 / 9} className="rounded-xl bg-muted">
        <div className="absolute inset-0 grid place-items-center text-sm text-muted-foreground">16:9</div>
      </AspectRatio>
    </div>
  );
}

API reference #

AspectRatio

component

Also accepts the native props of its root element and a ref.

PropTypeDefault
rationumber1
animatedbooleantrue
childrenReactNode—

AspectRatioImage

component

No props of its own; it accepts the native props of its root element.

Accessibility #

It is built on native elements, so roles and focus come from the browser.

No custom key handling; Tab and the native activation keys do the work.

Motion #

Transitions use the shared duration and easing tokens. Under prefers-reduced-motion those tokens collapse to instant and travel distances go to zero, so state changes still happen without movement.