Component reference
Box
A plan summary built from a token-aware surface primitive.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Team plan
Everything a growing team needs.
Spacing follows the shared token scale. Use named aliases when the exact step matters less than a consistent rhythm.
Width adapts to the available space
"use client";
import {
Card,
CardHeader,
CardTitle,
CardDescription,
CardContent,
Stack,
Box,
HStack,
Text,
Button,
Badge,
Paragraph
} 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>
<CardHeader>
<CardTitle>Team plan</CardTitle>
<CardDescription>Everything a growing team needs.</CardDescription>
</CardHeader>
<CardContent>
<Stack gap={4}>
<Box padding={4} background="muted">
<HStack justify="between" align="baseline">
<Text size="sm" tone="muted">per month</Text>
<Text size="xl" weight="semibold">€24</Text>
</HStack>
</Box>
<Stack gap={2}>
<Text size="sm">Unlimited projects</Text>
<Text size="sm">Shared themes</Text>
<Text size="sm">Priority support</Text>
</Stack>
<Button fullWidth>Choose the team plan</Button>
</Stack>
</CardContent>
</Card>
<Box padding={6} background="surface">
<Stack gap={3}>
<HStack gap={2} align="center">
<Badge variant="primary">Tip</Badge>
<Text size="sm" weight="medium">Space with tokens</Text>
</HStack>
<Paragraph size="sm" tone="muted">
Spacing follows the shared token scale. Use named aliases when
the exact step matters less than a consistent rhythm.
</Paragraph>
<Box padding={4} paddingX={6} background="muted">
<Text size="sm">A nested box resets the rhythm.</Text>
</Box>
</Stack>
</Box>
<Box
as="section"
aria-label="Notification summary"
padding={4}
paddingX={6}
background="surface"
>
<HStack gap={3} align="start">
<Badge variant="success">New</Badge>
<Stack gap={1}>
<Text weight="medium">Three files changed</Text>
<Text size="sm" tone="muted">
Review the pull request before the next release.
</Text>
</Stack>
</HStack>
</Box>
</div>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Padding scale
0, 1, 2, 3, 4, 6, 8 and 12 map to --pimolu-spacing-* tokens; the surface makes the padded area visible.
Axes
paddingX and paddingY refine the inline and block axes; p, px and py are aliases.
Surfaces
Only the semantic surface and muted tokens are available, so every preset and both themes stay consistent.
Usage
Use Box for layout and surface composition, not as a substitute for a semantic button or link.
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.
PimoluBoxProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
as | ElementType | undefined | `div` | Element rendered by the Box. Defaults to `div`. |
padding | PimoluBoxSpace | undefined | — | Padding on every side. |
p | PimoluBoxSpace | undefined | — | Shorthand for `padding`. |
paddingX | PimoluBoxSpace | undefined | — | Horizontal padding; wins over `padding` on the inline axis. |
px | PimoluBoxSpace | undefined | — | Shorthand for `paddingX`. |
paddingY | PimoluBoxSpace | undefined | — | Vertical padding; wins over `padding` on the block axis. |
py | PimoluBoxSpace | undefined | — | Shorthand for `paddingY`. |
background | PimoluBoxBackground | undefined | `none` (transparent) | Semantic surface tint. Defaults to `none` (transparent). |
fullWidth | boolean | undefined | false | Fill the available inline size. |
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 Box. Defaults to `div`.
paddingPimoluBoxSpace | undefinedNo default extracted.
Padding on every side.
pPimoluBoxSpace | undefinedNo default extracted.
Shorthand for `padding`.
paddingXPimoluBoxSpace | undefinedNo default extracted.
Horizontal padding; wins over `padding` on the inline axis.
pxPimoluBoxSpace | undefinedNo default extracted.
Shorthand for `paddingX`.
paddingYPimoluBoxSpace | undefinedNo default extracted.
Vertical padding; wins over `padding` on the block axis.
pyPimoluBoxSpace | undefinedNo default extracted.
Shorthand for `paddingY`.
backgroundPimoluBoxBackground | undefinedDefault: `none` (transparent)
Semantic surface tint. Defaults to `none` (transparent).
fullWidthboolean | undefinedDefault: false
Fill the available inline size.
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
- Choose the appropriate underlying semantic element and preserve reading order.