Overview
The AspectRatio component provides a container that maintains a specified aspect ratio, regardless of the parent container’s dimensions. It uses CSS custom properties and the aspect-ratio utility for consistent sizing.
Usage
import { AspectRatio } from "@kuzenbo/core";
export default function Example() {
return (
<AspectRatio
ratio={16 / 9}
className="border-border bg-card overflow-hidden rounded-lg border"
>
<div className="flex size-full flex-col justify-between p-4">
<div>
<div className="text-muted-foreground text-xs font-medium uppercase">
Q3 Spend Snapshot
</div>
<div className="mt-1 text-lg font-semibold">Procurement Overview</div>
</div>
<div className="grid grid-cols-3 gap-2 text-xs">
<div className="bg-muted rounded-md p-2">
<div className="text-muted-foreground">Approved</div>
<div className="mt-1 font-medium">$1.8M</div>
</div>
<div className="bg-muted rounded-md p-2">
<div className="text-muted-foreground">Pending</div>
<div className="mt-1 font-medium">$420K</div>
</div>
<div className="bg-muted rounded-md p-2">
<div className="text-muted-foreground">Blocked</div>
<div className="mt-1 font-medium">$86K</div>
</div>
</div>
</div>
</AspectRatio>
);
}
Common Ratios
16:9 (Widescreen)
import { AspectRatio } from "@kuzenbo/core";
export default function Widescreen() {
return (
<AspectRatio
ratio={16 / 9}
className="border-border bg-background overflow-hidden rounded-lg border"
>
<div className="grid size-full grid-cols-5 gap-0">
<div className="border-border bg-card col-span-3 border-r p-4">
<div className="text-sm font-medium">Release Readiness Dashboard</div>
<div className="text-muted-foreground mt-2 text-sm">
SLA compliance remains above target for all customer-facing systems.
</div>
</div>
<div className="col-span-2 grid grid-rows-2">
<div className="border-border bg-muted border-b p-3 text-xs">
Support backlog: 14 tickets
</div>
<div className="bg-muted p-3 text-xs">
Deployment window: 22:00 UTC
</div>
</div>
</div>
</AspectRatio>
);
}
1:1 (Square)
import { AspectRatio } from "@kuzenbo/core";
export default function Square() {
return (
<AspectRatio
ratio={1}
className="border-border bg-card overflow-hidden rounded-lg border"
>
<div className="grid size-full grid-rows-[auto_1fr_auto] gap-3 p-4">
<div className="text-sm font-medium">Warehouse Occupancy</div>
<div className="bg-muted grid content-center justify-items-center rounded-md text-center">
<div className="text-3xl font-semibold">82%</div>
<div className="text-muted-foreground text-xs">Capacity used</div>
</div>
<div className="text-muted-foreground text-xs">
6 of 11 docks are currently active.
</div>
</div>
</AspectRatio>
);
}
Props
The aspect ratio to maintain, expressed as width / height. Common values:
16 / 9 for widescreen (1.777…)4 / 3 for standard (1.333…)1 for square21 / 9 for ultrawide (2.333…)
Additional CSS classes to apply to the container.
Inline styles to apply. The component will merge these with the aspect ratio custom property.
div element props (ComponentProps<"div">).
Implementation
The component uses CSS custom properties to set the aspect ratio:
style={{
"--ratio": ratio,
} as CSSProperties}
aspect-(--ratio) utility.
Use Cases
- Media Placeholders: Maintain consistent dimensions for images or videos before loading
- Dashboard Cards: Create uniform card heights across responsive grids
- Thumbnails: Ensure consistent preview sizes regardless of content
- Hero Sections: Maintain banner proportions across breakpoints
Accessibility
The component includes a data-slot="aspect-ratio" attribute for styling and testing purposes. Content within the AspectRatio maintains normal accessibility as it’s a standard div container.