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.
alignSelf
AlignSelf
—
Cross-axis alignment of this flex item. Maps to align-self.
aria-description
LocalizedMessage
—
Extended description for assistive tech.
aria-label
LocalizedMessage | DisplayValue
—
Accessible name when the visible label is insufficient.
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
—
@deprecated Do not use outside the design system; use Box enum props or a shipped part.
Appended after the generated classes. Apps and remotes must not pass a className to restyle layout or paint
that Box props already express. For a flex column that fills remaining height and scrolls, use grow, shrink,
minHeight={BlockSize.Zero}, and overflow or overflowBlock (BX-3). When no enum prop exists, load the
find-pattern skill and request a typed prop instead of injecting styles.
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.
gradient
GradientPaint
—
State wash from the generated paint recipe: a diagonal gradient over its own ground, with the paired light text and
icon ladder applied to every descendant. Only blocks set it, from their own state; apps and remotes never choose
a wash. It is not a text color option: Text and Icon inside read the ordinary tokens. It composes with border,
borderRadius and elevation, but not with a background fill, which would sit under the wash ground.
grow
boolean
—
When true, sets flex-grow: 1.
height
SizedBlock
—
Block size. Replaces ui-core's free-form height.
item
FlexItem
—
Flex-item recipe for this node as a child of a flex container. Prefer item over className or CSS-module flex
shorthand. grow, shrink, and basis still work for advanced overrides.
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. BlockSize.Zero sets min-block-size: 0 so a flex child in a column can shrink and scroll
with grow, shrink, and overflow.
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.
regionClass
CssModuleClass
—
Token-only paint from a colocated *.region.module.scss import. Apps and remotes use this instead of
className on Box or FlexBox. The value must be branded {@link CssModuleClass}; plain strings are rejected
in development.
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 | DisplayValue
—
Native tooltip; accessibility hint, not visible UI title text.
CSS zoom at a discrete step from {@link ZOOM_STEPS }. Scales this node and its contents; layout reflows inside the
scaled box. Map a runtime fit with {@link toZoomStep } so content never exceeds its cell. Keep zoom at or above 0.4
for wall displays; text shrinks with the scale.
Layout
Box supports both block and flex layouts. Use display and flexDirection for flexbox layouts.
LayoutSize and Breakpoint size enums are documented on Layout size scale. LayoutSize applies to width and height axes; Breakpoint applies to maxWidth and maxHeight only.
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:
State wash (gradient)
gradient accepts GradientPaint: WashAccent, WashDestructive, and WashInformative (wash-accent, wash-destructive, wash-informative). Each applies the matching paint_wash_* recipe class. Only design-system blocks set it from their state; apps and remotes consume the block API instead.
The recipe layers the wash over --color-wash-ground, re-points descendant fg-* and icon-* tokens to --color-fg-on-wash-*, mirrors under :dir(rtl) with --gradient-wash-<id>-rtl, and removes the paint under prefers-contrast: more and forced-colors: active. There is no text color prop on a wash. Do not combine gradient with background on the same host.
See Storybook under Layout → Box → Props → Gradient (WashAccent, WashDestructive, WashInformative, AllWashes) for appearance and direction matrices.
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
Layout size and page caps
LayoutSize maps to Chroma --size-layout-* on an 8 / 16 / 50px ramp (8–96, 112–192, 200–1000 at a 16px root). Use it on width, minWidth, maxWidth, height, minHeight, and maxHeight when a column or panel should sit on the shared layout ramp instead of a one-off rem string.
Breakpoint names come from breakpoints.json. Use them on maxWidth and maxHeight only so page caps share the same px as media and container queries (centered-block 640px, content 800px, content-lg 960px, plus the desktop ladder).
zoom accepts a ZoomStep from ZOOM_STEPS (0.4 through 1.5 in 0.05 steps). Export toZoomStep to map a runtime number to the largest step at or below it. FlexBox and Grid use the same prop.
Popover widths
InlineSize.PopoverSm (10rem) and InlineSize.PopoverMd (18.75rem) size the content of a popover, the way DialogSm, DialogMd and DialogLg size dialogs. Both derive from --space-20, so they follow the space scale. Use them on width, minWidth or maxWidth of the popover's content root.
Placeholder height
BlockSize.Placeholder (10rem, 160px) is a fixed block size for a placeholder that reserves room for content that has not arrived, such as a metrics tile or an empty chart. It derives from the space scale (--space-128 plus --space-32) and does not follow the viewport the way Viewport25 does. Use it on height, minHeight or maxHeight; it also sizes a Skeleton and caps a Scrollable.
role
Box accepts structural roles only: group, region, none, presentation, status, alert, log, timer, list, listitem and img. Widget roles such as button belong on Interactable.
Use role="timer" for an elapsed or remaining time, such as a call duration. It is a non-interactive live region like status and log, and it is silent on each tick unless you set aria-live.
className
Deprecated outside the design system. Do not pass CSS module classes from apps or remotes to override layout or paint; use enum props, shipped parts, or the find-pattern skill to request a typed prop.
regionClass
regionClass accepts a branded CssModuleClass from import styles from "./….region.module.scss". Plain strings, template literals, and clsx output do not typecheck. In development, unbranded values throw at runtime.
Consumer stylelint (@prepared911/ui/stylelint) enforces token-only paint and the layout denylist on *.region.module.scss files. Host-only selectors apply: the host class alone or with :hover, :focus, :focus-visible, :focus-within, :active or :disabled; no descendants, :global, :has(), or design-system data-* hooks. Consumer files must not use @layer chroma.*. Paint that Box props already cover, such as a resting border or background, stays in props; the sidecar holds what props cannot express, such as state paint.
Colocate a *.region.module.scss.d.ts that types each class as CssModuleClass from @prepared911/ui/css-module-class; without it the import falls back to plain strings and does not typecheck. The build brands the classes: the shared Vite shell and remote configs, Vitest and Storybook apply the transform, and a Next.js app adds brandRegionScssModulesRule() from @prepared911/tooling-config/next/brand-region-scss-modules to its webpack rules.
Flex item (item)
Prefer item={FlexItem.*} over CSS-module flex shorthand on Box or FlexBox. Each enum bundles the grow, shrink, basis, and (where needed) minimum size and overflow rules ledger code repeats today.
FlexItem
CSS equivalent
Notes
Fixed
flex: 0 0 auto
Non-growing chrome
Fill
flex: 1 1 auto
Default flex child
FillZeroBasis
flex: 1 1 0
Equal flex siblings
FillNoShrink
flex: 1 0 auto
Main pane that must not shrink below content width
FillScroll
flex: 1 1 0 + min-height/min-width: 0 + overflow: auto
Scroll host inside a sized flex column (BX-3)
grow, shrink, and basis remain available for one-off tuning; avoid combining conflicting overrides with item.
Definite block size; optional Contents between parent and host
Flex column fill and scroll
item={FlexItem.FillScroll} or grow, minHeight={BlockSize.Zero}, overflow
Flex column parent
Grid cell fill
height={BlockSize.Full}, rows={GridRows.*}, same on cell content
Grid with definite block size
Flex column fill and scroll
A column that should use leftover height and scroll in place needs a definite height on the shell, then item={FlexItem.FillScroll} on the scrolling row (or explicit grow, shrink, minHeight={BlockSize.Zero}, and overflow).
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