Aspect Ratio
SaveA box that keeps a width-to-height ratio as it resizes, so images, video, and embeds fill it without shifting the layout.
- Category
- Data display
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Aspect Ratio preview
Installation
npx @shakenui/cli add aspect-ratioReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add aspect-ratio --dry-runUsage
aspect-ratio-example.tsx
import { AspectRatio } from "@/components/shaken/ui/aspect-ratio";
// A drawn preview stands in for a screenshot so the example has no network dependency.
function PreviewArt() {
return (
<svg viewBox="0 0 320 180" preserveAspectRatio="xMidYMid slice" aria-hidden="true" className="text-zinc-950 dark:text-white">
<rect width="320" height="180" className="fill-zinc-50 dark:fill-black" />
<rect x="0" y="0" width="320" height="22" className="fill-white dark:fill-black" />
<line x1="0" y1="22.5" x2="320" y2="22.5" stroke="currentColor" strokeOpacity="0.1" />
<circle cx="12" cy="11" r="3" fill="currentColor" fillOpacity="0.15" />
<circle cx="22" cy="11" r="3" fill="currentColor" fillOpacity="0.15" />
<circle cx="32" cy="11" r="3" fill="currentColor" fillOpacity="0.15" />
<rect x="16" y="38" width="72" height="6" rx="3" fill="currentColor" fillOpacity="0.7" />
<rect x="16" y="52" width="120" height="4" rx="2" fill="currentColor" fillOpacity="0.2" />
<path d="M16 150 L56 128 L96 136 L136 104 L176 112 L216 80 L256 90 L304 58" fill="none" stroke="currentColor" strokeWidth="2" strokeLinejoin="round" strokeLinecap="round" />
<path d="M16 150 L56 128 L96 136 L136 104 L176 112 L216 80 L256 90 L304 58 L304 164 L16 164 Z" fill="currentColor" fillOpacity="0.05" />
<line x1="16" y1="164.5" x2="304" y2="164.5" stroke="currentColor" strokeOpacity="0.15" />
</svg>
);
}
export default function AspectRatioExample() {
return (
<div className="grid w-full max-w-xl gap-4 sm:grid-cols-[2fr_1fr]">
<figure className="m-0 grid gap-2">
<AspectRatio ratio={16 / 9} className="rounded-xl border border-zinc-950/10 dark:border-white/10">
<PreviewArt />
</AspectRatio>
<figcaption className="text-xs text-zinc-500">Deploy preview, 16 by 9</figcaption>
</figure>
<figure className="m-0 grid content-start gap-2">
<AspectRatio ratio={1} className="rounded-xl border border-zinc-950/10 dark:border-white/10">
<PreviewArt />
</AspectRatio>
<figcaption className="text-xs text-zinc-500">Thumbnail, square crop</figcaption>
</figure>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| ratio | number | string | 16 / 9 | Width over height: 16 / 9, 1, or a CSS ratio string such as "4 / 3". |
| ...props | ComponentProps<"div"> | — | Any div attribute. Direct img, video, picture, iframe, and svg children fill the box with object-cover. |
Accessibility
- Purely presentational: it adds no role, so the media inside keeps its own alt text or title.
- Reserving the box's height before media loads prevents layout shift for every reader.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/aspect-ratio.tsxaspect-ratio- npm packages: noneReact and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/aspect-ratio/0.1.0.json.
ui/aspect-ratio.tsxShowHide
ui/aspect-ratio.tsx
import type { ComponentProps, CSSProperties } from "react";
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
export interface AspectRatioProps extends ComponentProps<"div"> {
/**
* Width divided by height: a number (`16 / 9`, `1`) or a CSS ratio string (`"4 / 3"`).
* Defaults to 16 / 9.
*/
ratio?: number | string;
}
/**
* A box that keeps its width-to-height ratio as it resizes, so media does not shift the layout
* while it loads. Direct `img`, `video`, `iframe`, `picture`, and `svg` children fill the box
* and crop with `object-cover`; anything else is laid out normally inside it.
*/
export function AspectRatio({ ratio = 16 / 9, className, style, ...props }: AspectRatioProps) {
return (
<div
data-slot="aspect-ratio"
style={{ aspectRatio: typeof ratio === "number" ? String(ratio) : ratio, ...style } as CSSProperties}
className={cx(
"relative w-full overflow-hidden",
"[&>img]:absolute [&>img]:inset-0 [&>img]:size-full [&>img]:object-cover",
"[&>video]:absolute [&>video]:inset-0 [&>video]:size-full [&>video]:object-cover",
"[&>picture]:absolute [&>picture]:inset-0 [&>picture]:size-full [&>picture>img]:size-full [&>picture>img]:object-cover",
"[&>iframe]:absolute [&>iframe]:inset-0 [&>iframe]:size-full [&>iframe]:border-0",
"[&>svg]:absolute [&>svg]:inset-0 [&>svg]:size-full",
className,
)}
{...props}
/>
);
}