AspectRatio
Explore interactive examples and all component variations in our Storybook.
The AspectRatio component constrains its children to a fixed aspect ratio. It is ideal for images, videos, thumbnails, and any media that must maintain proportional dimensions regardless of the available width.
Video (16:9)
16:9 Video
Square (1:1)
Portrait (3:4)
3:4 Portrait
Book cover / mobile
Photo (4:3)
4:3 Classic Photo
Responsive Image Grid
Nature
Architecture
Portrait
Abstract
Travel
Food
Properties
AspectRatio
| Property | Type | Default | Description |
|---|---|---|---|
ratio | number | - | The desired width-to-height ratio. For example, 16/9 for widescreen or 1 for square. |
className | string | - | Additional CSS classes applied to the wrapper element. |
children | ReactNode | - | Content to be constrained to the given ratio. Use h-full w-full on the child to fill the container. |
Common Ratios
| Name | Value | Typical Use |
|---|---|---|
| Widescreen | 16 / 9 | Video players, hero images, thumbnails |
| Classic photo | 4 / 3 | Traditional camera photos |
| Square | 1 | Profile pictures, avatars, product cards |
| Portrait | 3 / 4 | Book covers, mobile screenshots, posters |
| Cinematic | 21 / 9 | Wide banner images, cinematic video |
| Golden ratio | 1.618 | Editorial layouts |
Features
Intrinsic Sizing
AspectRatio uses a padding-based technique to maintain the ratio without requiring a fixed height, making it fully responsive to its container's width.
Works with Any Content
The component works with images, videos, iframes, custom placeholder divs, or any other content — just ensure the child has h-full w-full applied.
CSS-Based
No JavaScript is used at runtime to maintain the ratio, meaning there is no layout thrash or resize observers required.
Common Use Cases
- Media thumbnails — consistent video or image previews in grids and lists
- Profile pictures — square or circular avatar placeholders
- Hero images — full-width banners that scale proportionally
- Embedded videos — responsive iframes that maintain 16:9 without a fixed height
- Product cards — uniform product image sizes in e-commerce grids
- Book / album covers — portrait-oriented media in catalog views