Aspect Ratio

Displays content within a desired ratio.

tsx

1
2
3
4
5
6
7<AspectRatio ratio={16 / 9} className="w-full max-w-sm rounded-lg bg-muted">
  <img
    src="/avatars/01.png"
    alt="Photo"
    className="h-full w-full rounded-lg object-cover"
  />
</AspectRatio>

AspectRatio is a wrapper that forces its child to a given width/height ratio. Useful for embedding responsive images, videos or iframes without layout shift on load.

Implementation: native CSS aspect-ratio: W/H (Chrome 88+, Firefox 89+, Safari 15+). No JS, no padding hack.

Installation

Terminal

$ bext ui add aspect-ratio

Copy and paste the following into src/components/ui/aspect-ratio.tsx.

aspect-ratio.tsx

1
2
3
4
5
6
7<AspectRatio ratio={16 / 9} className="w-full max-w-sm rounded-lg bg-muted">
  <img
    src="/avatars/01.png"
    alt="Photo"
    className="h-full w-full rounded-lg object-cover"
  />
</AspectRatio>

Usage

tsx

1
2
3
4
5import { AspectRatio } from "@bext-stack/ui/primitives"

<AspectRatio ratio={16 / 9} className="w-full max-w-sm rounded-lg bg-muted">
  <img src="/photo.jpg" alt="Photo" className="h-full w-full object-cover rounded-lg" />
</AspectRatio>

Anatomy

<AspectRatio ratio={16 / 9}>{child}</AspectRatio>

API Reference

AspectRatio

Prop	Type	Default	Description
ratio	number \| string	"1/1"	Width/height ratio (`16 / 9`, `1 / 1`, `9 / 16`…). A string such as `"4/3"` is also accepted.
children	ReactNode	—	The content, typically an image (<img className="h-full w-full object-cover" />) or an iframe (<iframe className="h-full w-full" />).
className	string	—	Extra classes on the wrapper (relative w-full overflow-hidden), for example a rounded corner or a background.

Data Attributes

Attributes you can target in custom CSS to override the style for each state.

Attribute	On	Values	Description
data-slot="aspect-ratio"	AspectRatio root	—	Stable selector for custom styling. The ratio itself is an inline aspect-ratio style.

Accessibility

Purely decorative, no semantics added. If the content is an image, keep its alt. If it is an iframe, keep its title. For RTL layout, set dir="rtl" on an ancestor.

Examples

Square

tsx

1
2
3<AspectRatio ratio={1 / 1} className="w-full max-w-[12rem] rounded-lg bg-muted">
  <img src="…" alt="Photo" className="h-full w-full rounded-lg object-cover" />
</AspectRatio>

Portrait

tsx

1
2
3<AspectRatio ratio={9 / 16} className="w-full max-w-[10rem] rounded-lg bg-muted">
  <img src="…" alt="Photo" className="h-full w-full rounded-lg object-cover" />
</AspectRatio>

RTL

tsx

1
2
3
4
5
6
7
8<figure className="w-full max-w-sm" dir="rtl">
  <AspectRatio ratio={16 / 9} className="rounded-lg bg-muted">
    <img src="…" alt="منظر طبيعي جميل" className="h-full w-full rounded-lg object-cover" />
  </AspectRatio>
  <figcaption className="mt-2 text-center text-sm text-muted-foreground">
    منظر طبيعي جميل
  </figcaption>
</figure>

YouTube embed (16 / 9)

tsx

1
2
3
4
5
6
7
8<AspectRatio ratio={16 / 9} className="rounded-lg overflow-hidden">
  <iframe
    src="https://www.youtube.com/embed/..."
    className="h-full w-full"
    allow="autoplay; encrypted-media"
    allowFullScreen
  />
</AspectRatio>

Try it live Open in play

Edit this example live in the bext playground. It compiles and runs entirely in your browser.

src/app/page.tsx 1 file · react · runs in your browser

// An aspect-ratio box locks its child to a fixed width:height. Here a
// 16/9 frame stays in proportion however wide its container is.
export default function Page() {
  return (
    <main style={{ maxWidth: 640, margin: "0 auto", padding: "48px 20px", fontFamily: "Inter, system-ui, sans-serif" }}>
      <h1 style={{ letterSpacing: "-0.02em", marginBottom: 4 }}>Aspect Ratio</h1>
      <p style={{ color: "#64748b", marginTop: 0 }}>A box constrained to a fixed proportion.</p>
      <div style={{ marginTop: 22, maxWidth: 420 }}>
        <div style={{ aspectRatio: "16 / 9", borderRadius: 12, border: "1px solid #e2e8f0", background: "#f1f5f9", display: "flex", alignItems: "center", justifyContent: "center", color: "#475569", fontSize: 15, fontWeight: 600 }}>
          16 / 9
        </div>
        <p style={{ color: "#64748b", fontSize: 13, marginTop: 10 }}>The frame keeps its 16:9 shape at any width.</p>
      </div>
    </main>
  );
}

The React idiom: same UI, for comparison.

← Alert Dialog Avatar →

On This Page