Aspect Ratio
Constrains content to a fixed width-to-height ratio — useful for images, videos, and media embeds.
When To Use
- Use Aspect Ratio when you need a reusable atoms pattern instead of rebuilding the structure from primitives.
- Start from the simplest example that fits the task, then add decoration only when it clarifies meaning or hierarchy.
- Review the examples below to understand the tradeoffs between density, emphasis, and behavior.
When Not To Use
- Do not use Aspect Ratio just because it already exists in the catalog; choose the pattern that matches the task, not the most decorative option.
- Do not keep layering options onto the pattern when a simpler component or section would be easier to understand and maintain.
Accessibility Notes
- Keep headings, labels, and supporting text in the DOM before decorative chrome so the page reads well without styles or scripts.
- Test the pattern with keyboard navigation and a screen reader before treating the visual layout as complete.
- Use status, selection, and disabled states that remain understandable without color alone.
Key Props / API
Composition surface
Aspect Ratio keeps the native HTML or Radix API surface, then layers in design-system styling and composition defaults.
Example Code
import { AspectRatio } from "@hilum/ui"
<div className="w-full max-w-sm">
<AspectRatio ratio={16 / 9} className="bg-ground-100 rounded-xl flex items-center justify-center">
<span className="label text-ground-400">16 : 9</span>
</AspectRatio>
</div>Variants
16:9
Widescreen video and image ratio
16 : 9
4:3
Classic photo and presentation ratio
4 : 3
1:1
Square — ideal for avatars and thumbnails
1 : 1
Portrait 2:3
Tall portrait format for cards and posters
2 : 3 Portrait