Box

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

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`	—	Cross-axis alignment when the display is flex or grid.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	Accessible name when the visible label is insufficient.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`as`	`"div" \| "section" \| "article" \| "aside" \| "header" \| "footer" \| "main" \| "nav" \| "search" \| "figure" \| "figcaption" \| "address" \| "blockquote" \| "form" \| "fieldset" \| "ul" \| "ol" \| ... 7 more ...`	—	Element to render. Defaults to `div`.
`attachBlockEnd`	`boolean`	—	Pins the block-end edge. Replaces ui-core `attachBottom`.
`attachBlockStart`	`boolean`	—	Pins the block-start edge. Replaces ui-core `attachTop`.
`attachInlineEnd`	`boolean`	—	Pins the inline-end edge. Replaces ui-core `attachRight`.
`attachInlineStart`	`boolean`	—	Pins the inline-start edge. Replaces ui-core `attachLeft`.
`background`	`Background`	—	Fill from a background token.
`basis`	`FlexBasis`	—	Initial main size. Maps to `flex-basis`.
`border`	`BorderColor`	—	Border on every side.
`borderBlockEnd`	`BorderColor`	—	Border on the block-end side. Replaces ui-core `borderBottom`.
`borderBlockStart`	`BorderColor`	—	Border on the block-start side. Replaces ui-core `borderTop`.
`borderInlineEnd`	`BorderColor`	—	Border on the inline-end side. Replaces ui-core `borderRight`.
`borderInlineStart`	`BorderColor`	—	Border on the inline-start side. Replaces ui-core `borderLeft`.
`borderRadius`	`Radius`	—	Corner radius token.
`borderWidth`	`BorderWidth`	—	Border thickness for whichever sides are on.
`children`	`ReactNode`	—	Content rendered inside the element.
`className`	`string`	—	Classes for styles Box props do not cover, such as `:hover` and other interaction states. Appended after the generated classes. Put the rules in `@layer chroma.overrides` so they win over any Box prop for the same property, and reference only allowlisted tokens.
`containerType`	`ContainerType`	—	CSS `container-type`.
`display`	`Display`	—	CSS `display`.
`elevation`	`Elevation`	—	Shadow token. Does not change the background.
`flexDirection`	`FlexDirection`	—	Flex main axis.
`flexWrap`	`FlexWrap`	—	Flex wrapping.
`gap`	`Gap`	—	Space between children. Maps to `gap`.
`grow`	`boolean`	—	When true, sets `flex-grow: 1`.
`height`	`SizedBlock`	—	Block size. Replaces ui-core's free-form `height`.
`justifyContent`	`JustifyContent`	—	Main-axis alignment when the display is flex or grid.
`loading`	`boolean`	—	Paints this box as its own loading placeholder, sized by its own layout. The fill matches `Skeleton`: `--color-fill-strong` (unchanged from before) is painted at once and opacity pulses 0.6, 1, 0.6 (the range it always had) over 1.8s on `--easing-glide-in-out` for 11 cycles, staggered 90ms per sibling, then rests at 0.6. The pulse stops under reduced motion, increased contrast and forced colors. The box is inert and hidden from assistive tech; set `aria-busy` on the region that owns the data.
`margin`	`Margin`	—	Margin from the space scale, including the negative steps.
`maxHeight`	`MaxBlockSize`	—	Maximum block size.
`maxWidth`	`MaxInlineSize`	—	Maximum inline size.
`minHeight`	`SizedBlock`	—	Minimum block size.
`minWidth`	`SizedInline`	—	Minimum inline size.
`overflow`	`Overflow`	—	CSS `overflow`.
`overflowBlock`	`Overflow`	—	Block-axis overflow when the shorthand is not enough.
`overflowInline`	`Overflow`	—	Inline-axis overflow when the shorthand is not enough.
`padding`	`Spacing`	—	Padding from the space scale, on all sides or per logical side.
`position`	`Position`	—	CSS `position`.
`ref`	`Ref<BoxHost<T>>`	—	Ref to the rendered element.
`shrink`	`boolean`	—	When true, sets `flex-shrink: 1` and `min-inline-size: 0` so flex children can shrink below their content width. When false, sets `flex-shrink: 0`. Omitted by default.
`state`	`StateAttributesInput`	—	Design-system state attributes. Raw `data-*` state names are reserved.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`width`	`SizedInline`	—	Inline size. Replaces ui-core's free-form `width`.
`zIndex`	`ZIndex`	—	Stacking 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

Box