Aspect Ratio
Maintain consistent proportions for images, videos, and other content.
The AspectRatio component maintains a consistent width-to-height proportion for its content.
It uses the native CSS aspect-ratio property, making it suitable for responsive media containers, image galleries, video embeds, and other layouts where predictable proportions are important.
Import
import { AspectRatio } from "@puzzle-ui/ui";Basic usage
By default, AspectRatio uses a square (1:1) ratio.
Aspect ratios
Use the ratio prop to define the desired width-to-height proportion.
The ratio is expressed as a number. For example, 16 / 9 represents a widescreen aspect ratio, while 4 / 3 represents a traditional display ratio.
The aspect ratio is maintained automatically as the container width changes.
Images
AspectRatio is particularly useful for responsive images.
Combine it with object-fit: cover to fill the container while preserving the image's proportions.
For square images, such as avatars or product thumbnails, use the default ratio.
Video embeds
Use AspectRatio to maintain the correct proportions of embedded videos.
For example, a 16:9 container is suitable for most YouTube and other widescreen video embeds.
Custom elements
Use the as prop to change the underlying HTML element.
All native properties supported by the selected element are forwarded to the root element.
Styling
AspectRatio supports both className and style.
Custom styles are merged with the component's internal styles. The ratio prop takes precedence over style.aspectRatio.
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
ratio | number | 1 | Width-to-height ratio. Must be a positive finite number. |
as | ElementType | "div" | HTML element or component used as the root. |
className | string | — | Additional CSS class names. |
style | CSSProperties | — | Additional inline styles. |
children | ReactNode | — | Content displayed inside the aspect ratio container. |
All other native props supported by the selected root element are forwarded.
TypeScript types
type AspectRatioProps<C extends ElementType = "div"> = AspectRatioOwnProps<C> &
Omit<ComponentPropsWithRef<C>, keyof AspectRatioOwnProps<C> | "as">;The component also exports AspectRatioProps for use in custom components and wrappers.
Behavior
- The default ratio is
1, producing a square container. - The
ratioprop accepts any positive finite number. - Invalid ratios, including zero, negative values,
NaN, and infinity, throw aRangeError. - The component uses the native CSS aspect-ratio property.
- The container fills the available width of its parent.
- Direct children are positioned to fill the container.
- Custom styles and classes are supported.
- The component does not require JavaScript layout calculations or browser observers.
Accessibility
AspectRatio is a layout primitive and does not introduce additional ARIA roles or keyboard interactions.
The underlying HTML element determines its semantics.
When displaying images:
- Always provide meaningful
alttext for informative images. - Use an empty
altattribute for purely decorative images. - Avoid using CSS backgrounds for images that convey meaningful information.
When embedding videos or iframes, provide an accessible title and ensure that the embedded content remains usable with a keyboard.