Layout · astro-ui · AspectRatio

AspectRatio

Reserves a fixed width/height ratio for media — no layout shift.

AspectRatio wraps a single child (img, video, iframe, or div) in a box with a fixed CSS aspect-ratio and stretches the child to fill it. Drop media in and it covers the box without layout shift — object-fit stays in your hands.

← All components

Features

CSS aspect-ratio — number (1.78) or string ("16 / 9")
Child stretches to fill; object-fit stays consumer-controlled
Overflow hidden — no media bleeding past the box
Zero JS, no layout shift

Usage

---
import { AspectRatio } from "astro-ui";
---

<AspectRatio ratio="16 / 9">
  <img src="hero.jpg" alt="Hero" class="object-cover" />
</AspectRatio>

Demos

Common ratios

<AspectRatio ratio="16 / 9">
  <img src="…" alt="" class="object-cover" />
</AspectRatio>
<AspectRatio ratio="4 / 3">…</AspectRatio>
<AspectRatio ratio={1}>…</AspectRatio>

Widescreen

<AspectRatio ratio="21 / 9">…</AspectRatio>
<AspectRatio ratio="16 / 10">…</AspectRatio>

Portrait

<AspectRatio ratio="9 / 16">…</AspectRatio>
<AspectRatio ratio="4 / 5">…</AspectRatio>

Photo

<AspectRatio ratio="3 / 2">…</AspectRatio>
<AspectRatio ratio={1}>…</AspectRatio>

API

Props

Prop	Type	Default	Description
`ratio`	`number \| string`	`1`	CSS aspect-ratio value: number (1.78) or string ("16 / 9").
`class`	`string`	`—`	Merged via cn(); Tailwind classes welcome.
`id`	`string`	`—`	Element id.

Slots

Slot	Description
`default`	Media stretched to fill the box.

Accessibility

Implemented accessibility features — semantics, ARIA wiring, and keyboard behavior that ship with the component.

FAQ

Why doesn't my image fill the box?

The child is stretched to 100%×100% — add object-cover (or object-contain) on the img so it fills without distortion.

Changelog

Version history mentioning AspectRatio.

v0.1.0 — 2026-11-11

added

Layout (7): Card, AspectRatio, ScrollArea, Separator, Accordion, Collapsible, StickySurface.