Prepared Docs

The Box component is the fundamental layout building block in our design system. It provides a flexible container that can be styled with various properties for spacing, borders, backgrounds, and more.

Basic Usage

Simple box with padding and a background.

Props

FlexBox accepts the same props as Box (it wraps Box with flex display by default). The table below applies to both. The only API difference is that FlexBox narrows display to flex or inline-flex; Box supports every Display value.

Name	Type	Default	Description
`alignItems`	`AlignItems`	—	Controls cross-axis alignment of flex children. Maps to CSS `align-items`.
`attachBottom`	`boolean`	—	Removes bottom border-radius, making the box flush against the bottom edge.
`attachLeft`	`boolean`	—	Removes left border-radius, making the box flush against the left edge.
`attachRight`	`boolean`	—	Removes right border-radius, making the box flush against the right edge.
`attachTop`	`boolean`	—	Removes top border-radius, making the box flush against the top edge.
`background`	`Background`	—	Applies a semantic background color token to the box.
`basis`	`string`	—	Sets the initial main size of the flex item. Maps to CSS `flex-basis`.
`border`	`Border`	—	Applies a border style to all sides of the box.
`borderBottom`	`Border`	—	Applies a border style to only the bottom side.
`borderLeft`	`Border`	—	Applies a border style to only the left side.
`borderRadius`	`BorderRadius`	—	Sets the border radius using a design token.
`borderRight`	`Border`	—	Applies a border style to only the right side.
`borderTop`	`Border`	—	Applies a border style to only the top side.
`className`	`string`	—	Additional CSS class name(s) to apply to the box element.
`containerType`	`ContainerType`	—	Enables CSS container queries by setting the `container-type` property.
`display`	`Display`	`Display.Flex`	Sets the CSS `display` property.
`elevation`	`Elevation`	—	Applies a box-shadow elevation level for depth/layering.
`flexDirection`	`FlexDirection`	—	Sets the direction of the flex container's main axis. Maps to CSS `flex-direction`.
`flexWrap`	`FlexWrap`	—	Controls whether flex items wrap onto multiple lines. Maps to CSS `flex-wrap`.
`gap`	`Gap`	—	Spacing between child elements. Maps to CSS `gap`.
`grow`	`boolean`	—	When true, sets `flex-grow: 1` so the element expands to fill available space.
`justifyContent`	`JustifyContent`	—	Controls main-axis alignment of flex children. Maps to CSS `justify-content`.
`margin`	`Spacing`	—	Outer spacing around the box. Accepts a spacing token.
`onClick`	`MouseEventHandler<HTMLDivElement>`	—	Click handler forwarded to the underlying element (along with other DOM props in `...props`).
`onKeyDown`	`KeyboardEventHandler<HTMLDivElement>`	—	Keydown handler forwarded to the underlying element. Useful for div-based controls that need to respond to Enter/Space like a button.
`onPointerDown`	`PointerEventHandler<HTMLDivElement>`	—	Pointer down handler forwarded to the underlying element.
`overflow`	`Overflow`	—	Controls overflow behavior for content that exceeds the box dimensions.
`padding`	`Spacing`	—	Inner spacing within the box. Accepts a spacing token.
`position`	`Position`	—	Sets the CSS `position` property for layout positioning.
`ref`	`Ref<HTMLDivElement>`	—	React ref forwarded to the underlying `<div>` element.
`shrink`	`boolean`	`true`	When true, sets `flex-shrink: 1` so the element can shrink below its initial size.
`style`	`CSSProperties`	—	Inline styles applied directly to the box element.
`whiteSpace`	`WhiteSpace`	—	Controls the CSS `white-space` property for text wrapping behavior.
`zIndex`	`ZIndex`	—	Sets the CSS `z-index` stacking order using a design token.

Layout

Box supports both block and flex layouts. Use display and flexDirection for flexbox layouts.

FlexBox

When using Flex you can also use an alias called FlexBox that adds display={Display.Flex} for you.

Spacing

Box supports both margin and padding with a consistent spacing scale:

Positioning

Box supports various positioning options.

Display types

White space

Flex row

Flex column

Borders

Elevations

Overflow

Z-index levels

Flex grow and shrink

Padding and margin

FlexBox shrinks to parent

Best Practices

Avoid nesting too many Box components. Consider using semantic HTML elements when possible and only use Box for styling purposes.

Use FlexBox for Layouts
- Prefer FlexBox over Box display={Display.Flex} for flex layouts
- Use gap prop for consistent spacing between flex items
Responsive Design
- Use relative units for width/height when possible
- Consider using grow and shrink for flexible layouts
Performance
- Box components are memoized for better performance
- Avoid unnecessary nesting of Box components
Accessibility
- Use semantic HTML elements when possible

Common Patterns

Card Pattern

Box / Usage

Circle / Usage

View Source

Submit Issue