Component reference
AspectRatio
Keep product media in a predictable frame.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.

Pimolu Studio
NewThe media reserves its space, so the card does not jump when the image arrives.
Video embed
16 / 9 matches the default video frame.
Gallery tile
A square tile keeps a grid of different products aligned.

Everyday collection
Square media is predictable in a masonry or a carousel.
Width adapts to the available space
"use client";
import {
Card,
AspectRatio,
CardHeader,
HStack,
CardTitle,
Badge,
CardDescription,
CardContent,
Text,
Box,
Stack,
Heading,
Paragraph,
Button
} from "@pimolu/react";
export function DemoExample() {
return (
<div
className="grid grid-cols-[repeat(auto-fit,minmax(min(100%,280px),1fr))] gap-6 min-w-0 items-start"
>
<Card>
<AspectRatio ratio={16 / 9}>
<img
src="/images/pimolu-studio.webp"
alt="Pimolu Studio headphones with the p emblem"
/>
</AspectRatio>
<CardHeader>
<HStack justify="between" align="center">
<CardTitle>Pimolu Studio</CardTitle>
<Badge variant="success">New</Badge>
</HStack>
<CardDescription>
The media reserves its space, so the card does not jump when the
image arrives.
</CardDescription>
</CardHeader>
<CardContent>
<Text weight="semibold">€129</Text>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>Video embed</CardTitle>
<CardDescription>16 / 9 matches the default video frame.</CardDescription>
</CardHeader>
<CardContent>
<AspectRatio
ratio={16 / 9}
style={{
borderRadius: "var(--pimolu-radius-md)",
overflow: "hidden",
}}
>
<Box
background="muted"
fullWidth
style={{
display: "flex",
alignItems: "center",
justifyContent: "center",
}}
>
<Stack gap={2} align="center">
<Text weight="medium">Video placeholder</Text>
<Text size="sm" tone="muted">iframe, video or canvas fills the box</Text>
</Stack>
</Box>
</AspectRatio>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>Gallery tile</CardTitle>
<CardDescription>
A square tile keeps a grid of different products aligned.
</CardDescription>
</CardHeader>
<CardContent>
<Stack gap={3}>
<AspectRatio ratio={1}>
<img
src="/images/pimolu-studio.webp"
alt="Pimolu Studio, square crop"
/>
</AspectRatio>
<Stack gap={1}>
<Heading level={3} size="md">Everyday collection</Heading>
<Paragraph size="sm" tone="muted">
Square media is predictable in a masonry or a carousel.
</Paragraph>
<Button size="sm" appearance="outline">Browse the collection</Button>
</Stack>
</Stack>
</CardContent>
</Card>
</div>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Ratios
The default is 16 / 9; any positive finite number works. Invalid values fall back to the default.
Non-media content
The content wrapper is a grid, so a non-image child stretches to the reserved area.
Invalid fallbacks
Zero, negative and non-finite values keep the 16 / 9 default instead of collapsing the box.
Usage
Choose a ratio appropriate to the media without distorting its content.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluAspectRatioProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
as | ElementType | undefined | `div` | Element rendered by the outer box. Defaults to `div`. |
ratio | number | undefined | `16 / 9` | Width divided by height. Defaults to `16 / 9`. Invalid or non-positive values fall back to the default. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
children | ReactNode | — | Standard React/HTML attribute. |
onChange | ChangeEventHandler<HTMLElement, Element> | undefined | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLElement> | undefined | — | Standard React/HTML attribute. |
asElementType | undefinedDefault: `div`
Element rendered by the outer box. Defaults to `div`.
rationumber | undefinedDefault: `16 / 9`
Width divided by height. Defaults to `16 / 9`. Invalid or non-positive values fall back to the default.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
childrenReactNodeNo default extracted.
Standard React/HTML attribute.
onChangeChangeEventHandler<HTMLElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLElement> | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Provide image alternatives and retain a usable layout if the image fails.