Atom

Box

Polymorphic layout primitive with system props for spacing, sizing, flex, colors, and more.

Overview

The Box component is a low-level layout primitive that provides system props for styling. It's polymorphic (can render as any HTML element) and accepts props for spacing, sizing, flexbox, colors, borders, and more - all using design tokens.

A simple box with padding, background, and shadow

Props

Base Props

Prop	Type	Default	Description
`as`	`ElementType`	`'div'`	HTML element to render
`children`	`ReactNode`	-	Box content

Spacing Props

Prop	Type	Description
`p`	`number \| string`	Padding (all sides)
`px`	`number \| string`	Horizontal padding
`py`	`number \| string`	Vertical padding
`pt, pr, pb, pl`	`number \| string`	Individual padding sides
`m`	`number \| string`	Margin (all sides)
`mx`	`number \| string`	Horizontal margin
`my`	`number \| string`	Vertical margin
`mt, mr, mb, ml`	`number \| string`	Individual margin sides
`gap`	`number \| string`	Gap between children
`rowGap, columnGap`	`number \| string`	Individual gap directions

Sizing Props

Prop	Type	Description
`width, height`	`number \| string`	Dimensions
`minWidth, maxWidth`	`number \| string`	Width constraints
`minHeight, maxHeight`	`number \| string`	Height constraints

Flex Props

Prop	Type	Description
`display`	`string`	Display property
`flexDirection`	`string`	Flex direction
`flexWrap`	`string`	Flex wrapping
`justifyContent`	`string`	Main axis alignment
`alignItems`	`string`	Cross axis alignment
`alignContent`	`string`	Multi-line alignment
`alignSelf`	`string`	Self alignment
`flex`	`string \| number`	Flex shorthand
`flexGrow, flexShrink, flexBasis`	`string \| number`	Individual flex properties
`order`	`number`	Flex order

Position Props

Prop	Type	Description
`position`	`string`	Position type
`top, right, bottom, left`	`number \| string`	Position offsets
`zIndex`	`number \| string`	Stack order

Style Props

Prop	Type	Description
`bg`	`string`	Background color
`color`	`string`	Text color
`border`	`string`	Border (all sides)
`borderTop, borderRight, borderBottom, borderLeft`	`string`	Individual borders
`borderColor`	`string`	Border color
`radius`	`RadiusToken`	Border radius (all corners)
`radiusTopLeft, radiusTopRight, radiusBottomLeft, radiusBottomRight`	`RadiusToken`	Individual corner radii
`overflow, overflowX, overflowY`	`string`	Overflow behavior
`elevation`	`ElevationToken`	Box shadow

Token Types Reference

RadiusToken: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'
ElevationToken: 100 | 200 | 300 | 400 | 'none'

Examples

Flex Container

Using Box as a flex container with gap.

Item 1

Item 2

Item 3

<Box display="flex" gap={12} p={16} bg="var(--background-base)" radius="md">
  <Box p={12} bg="var(--background-primary-subtle)" radius="sm">Item 1</Box>
  <Box p={12} bg="var(--background-primary-subtle)" radius="sm">Item 2</Box>
  <Box p={12} bg="var(--background-primary-subtle)" radius="sm">Item 3</Box>
</Box>

Card-like Container

Box styled as a card with elevation.

Card Title

This is a card-like container built with Box component.

<Box p={24} bg="var(--background-base)" radius="lg" elevation={200}>
  <Text variant="title">Card Title</Text>
  <Box mt={8}>
    <Text color="muted">Card content...</Text>
  </Box>
</Box>

Polymorphic Usage

Render Box as different HTML elements.

Rendered as <section>

Rendered as <article>

<Box as="section">...</Box>
<Box as="article">...</Box>
<Box as="aside">...</Box>

Spacing with Numbers

Numeric values are converted to pixels.

p=8 m=4 (8px padding, 4px margin)

p=16 m=8 (16px padding, 8px margin)

p=24 m=12 (24px padding, 12px margin)

Accessibility

Best Practices

Use semantic HTML elements via the 'as' prop when appropriate
Use design tokens (CSS variables) for colors and sizes when possible
Prefer higher-level components (Card, Stack) for common patterns
Keep Box usage for custom layouts that don't fit standard patterns