Primitive / Atombeta

Aspect Ratio

Constrains content to a width to height ratio with optional surface frame.

Edit on GitHub

pnpm dlx @glinui/cli@latest add aspect-ratio

16:9

4:3

1:1

9:16

Installation

Install from

pnpm dlx @glinui/cli@latest add aspect-ratio

Prefer the package?

Usage

Variants

Every vocabulary variant on the default tone. Omit variant to follow the ambient design style.

glinr

solid

soft

outline

ghost

gradient

import { AspectRatio } from "@glinui/ui"


export function AspectRatioVariantsDemo() {
  return (
    <div className="grid gap-4 md:grid-cols-3">
      <AspectRatio variant="glinr" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">glinr</div></AspectRatio>
      <AspectRatio variant="solid" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">solid</div></AspectRatio>
      <AspectRatio variant="soft" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">soft</div></AspectRatio>
      <AspectRatio variant="outline" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">outline</div></AspectRatio>
      <AspectRatio variant="ghost" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">ghost</div></AspectRatio>
      <AspectRatio variant="gradient" ratio={16 / 9}><div className="grid size-full place-items-center text-sm">gradient</div></AspectRatio>
    </div>
  )
}

In a card

A 16:9 cover on top of a card.

Guide

Designing empty states

Six patterns that turn a blank screen into the next step.

import { Sparkle } from "@phosphor-icons/react"
import { AspectRatio, Badge, Card } from "@glinui/ui"


export function Demo() {
  return (
    <Card className="w-full max-w-sm overflow-hidden p-0">
      <AspectRatio ratio={16 / 9}>
        <div className="flex size-full items-center justify-center bg-gradient-to-br from-[var(--color-accent)] to-[var(--surface-3)]">
          <Sparkle aria-hidden weight="fill" className="size-10 text-white" />
        </div>
      </AspectRatio>
      <div className="flex flex-col gap-2 p-4">
        <Badge variant="soft" tone="accent" size="sm" className="w-fit">Guide</Badge>
        <h3 className="text-base font-semibold">Designing empty states</h3>
        <p className="text-sm text-[var(--color-muted)]">Six patterns that turn a blank screen into the next step.</p>
      </div>
    </Card>
  )
}

Accessibility

Layout-only primitive with no implicit role.
Provide `alt` on images or `aria-label` on media placed inside.

ARIA Attributes

No ARIA attributes are added.

Reduced Motion

No motion is used.

API Reference

Prop	Type	Required	Default	Description
`ratio`	`number`	-	`1`	Width divided by height, e.g. 16 / 9.
`variant`	`SurfaceVariant \| "default"`	No	`plain (chromeless)`	Surface variant. Omit to follow the ambient design style (glinr by default, plain for minimal, glass for glass).
`tone`	`SurfaceTone`	No	`neutral`	Colour tone for the vocabulary variants.
`className`	`string`	-	`-`	Merged onto the frame.

Source

Import directly from the package or browse the source on GitHub. Click any file to view it.

Import

import { AspectRatio } from "@glinui/ui"

Source Files

aspect-ratio.tsx

aspect-ratio.test.tsxtest

Dependencies

@glinui/ui@radix-ui/react-aspect-ratioclass-variance-authority

Generated API Snapshot

Beta

Auto-extracted from TypeScript source in packages/ui/src/components/aspect-ratio.tsx. This section is in beta and may lag behind hand-curated docs. Regenerate with pnpm --filter @glinui/docs api:generate.

Generated: 2026-10-08T01:41:21.546Z · Full index: /docs/api-metadata

Primary Props Type

AspectRatioProps

`AspectRatioProps`

Prop	Type	Required	Default	Description
`tone`	`SurfaceTone`	No	`-`	-
`variant`	`SurfaceVariant \| "default"`	No	`-`	Surface variant. Omit (or `plain`) for a chromeless frame like the shadcn primitive. Vocabulary: glinr, solid, soft, outline, ghost, gradient, glass. Legacy `default` maps to glinr.