Layout
Box
A flexible layout primitive with responsive props for spacing, layout, positioning, borders, background, and more.
Box
The Box component is a highly flexible, composable layout primitive. It’s the foundation for spacing, alignment, background, borders, shadows, and positioning across the system. All layout props support responsive values via arrays.
Prefer composition over custom CSS. Box exposes common layout concerns while keeping your markup simple and consistent.
Features
- Responsive props for spacing and layout
- Background, border, and shadow tokens
- Flex, grid, inline and block display modes
- Positioning (relative, absolute, fixed, sticky) and offsets
- Shorthand spacing and gap tokens for consistent rhythm
- Optional as to change element tag and asChild to style an existing element
Usage
import { Box } from '@loke/design-system/box';
export default function Example() {
return (
<Box
padding={4}
margin={[2, 4]}
background="primary"
borderRadius="md"
display="flex"
alignItems="center"
justifyContent="center"
>
<p className="text-primary-foreground">Content goes here</p>
</Box>
);
}Tips:
- Use responsive arrays to change values at breakpoints: padding=2468
- Compose Box with other primitives (e.g., Stack/Inline/Columns) for predictable layouts
- Use asChild to style an existing element or component while retaining Box styling
Props
Prop
Type
Examples
Default
Example Content
<Box background="primary" borderRadius="md" padding={4}>
<div className="bg-secondary p-4 text-secondary-foreground">Example Content</div>
</Box>Responsive padding
Responsive Padding
<Box background="accent" borderRadius="lg" padding={[2, 4, 6, 8]}>
<div className="bg-secondary p-4 text-secondary-foreground">Responsive Padding</div>
</Box>Flex layout
Item A
Item B
Item C
<Box
background="background"
borderRadius="xl"
display="flex"
flexDirection="row"
gap={4}
padding={4}
>
<div className="bg-secondary p-4 text-secondary-foreground">Item A</div>
<div className="bg-secondary p-4 text-secondary-foreground">Item B</div>
<div className="bg-secondary p-4 text-secondary-foreground">Item C</div>
</Box>Responsive flex direction and gap
Item 1
Item 2
Item 3
<Box
background="foreground"
borderRadius="2xl"
display="flex"
flexDirection={["col", "row", "row", "row"]}
gap={[2, 4, 6, 8]}
padding={4}
>
{/* children */}
</Box>Grid layout
1
2
3
4
<Box
background="primary"
borderRadius="3xl"
className="grid-cols-2"
display="grid"
gap={4}
padding={4}
>
{/* children */}
</Box>Bordered
Bordered
<Box border borderColor="primary" borderRadius="md" padding={4}>
Content
</Box>Shadow
Shadow Box
<Box background="background" borderRadius="lg" boxShadow="2xl" padding={4}>
Content
</Box>Positioned (absolute within relative)
Absolute
<Box background="primary" borderRadius="lg" height={32} position="relative">
<Box position="absolute" top={4} left={4} background="accent" borderRadius="md" padding={4} />
</Box>Overflow with fixed height
Item 1
Item 2
Item 3
Item 4
Item 5
Item 6
Item 7
Item 8
Item 9
Item 10
<Box
display="flex"
height={32}
overflow="auto"
width={["3/4", "1/2"]}
padding={4}
background="secondary"
borderRadius="xl"
>
{/* many children */}
</Box>Responsive width
Responsive width
<Box padding={4} background="primary" borderRadius="lg" width={["full", "3/4", "1/2", "1/4"]} />Container
Container (responsive max-width)
<Box container padding={4} background="background" borderRadius="xl" />Responsive display
Item 1
Item 2
Item 3
<Box
display={["block", "hidden", "grid", "flex"]}
className="grid-cols-3"
border
borderColor="neutral-200"
borderRadius="md"
padding={4}
/>Using asChild
asChild lets Box style and control layout for an existing child element/component without introducing an extra DOM wrapper.
This renders as a <section>
Box styles are applied to the section element.
<Box asChild padding={4} border borderColor="primary" borderRadius="md" background="background">
<section>…</section>
</Box>Best practices
- Keep layout in Box and content semantics in native tags via as or asChild
- Prefer semantic color tokens (e.g., background, primary) over hard-coded classes
- Use responsive arrays to adapt spacing and layout across breakpoints
- Combine with Stack/Inline/Columns for predictable vertical, horizontal, and grid layouts