Axon 911 Frontend DocsAxon 911 Frontend Docs
Axon 911 Frontend Docs
    Loading navigation…
U
User
Switch to light mode
  1. Primitives
  3. Box
  5. API and Development

Box

API and Development

View SourceOpens in a new tabSubmit 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.
NameTypeDefaultDescription
alignItemsAlignItems—Cross-axis alignment when the display is flex or grid.
alignSelfAlignSelf—Cross-axis alignment of this flex item. Maps to align-self.
aria-descriptionLocalizedMessage—Extended description for assistive tech.
aria-labelLocalizedMessage | DisplayValue—Accessible name when the visible label is insufficient.
aria-placeholderLocalizedMessage—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.
attachBlockEndboolean—Pins the block-end edge. Replaces ui-core attachBottom.
attachBlockStartboolean—Pins the block-start edge. Replaces ui-core attachTop.
attachInlineEndboolean—Pins the inline-end edge. Replaces ui-core attachRight.
attachInlineStartboolean—Pins the inline-start edge. Replaces ui-core attachLeft.
backgroundBackground—Fill from a background token.
basisFlexBasis—Initial main size. Maps to flex-basis.
borderBorderColor—Border on every side.
borderBlockEndBorderColor—Border on the block-end side. Replaces ui-core borderBottom.
borderBlockStartBorderColor—Border on the block-start side. Replaces ui-core borderTop.
borderInlineEndBorderColor—Border on the inline-end side. Replaces ui-core borderRight.
borderInlineStartBorderColor—Border on the inline-start side. Replaces ui-core borderLeft.
borderRadiusRadius—Corner radius token.
borderWidthBorderWidth—Border thickness for whichever sides are on.
childrenReactNode—Content rendered inside the element.
classNamestring—@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.
containerTypeContainerType—CSS container-type.
displayDisplay—CSS display.
elevationElevation—Shadow token. Does not change the background.
flexDirectionFlexDirection—Flex main axis.
flexWrapFlexWrap—Flex wrapping.
gapGap—Space between children. Maps to gap.
growboolean—When true, sets flex-grow: 1.
heightSizedBlock—Block size. Replaces ui-core's free-form height.
itemFlexItem—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.
justifyContentJustifyContent—Main-axis alignment when the display is flex or grid.
loadingboolean—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.
marginMargin—Margin from the space scale, including the negative steps.
maxHeightMaxBlockSize—Maximum block size.
maxWidthMaxInlineSize—Maximum inline size.
minHeightSizedBlock—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.
minWidthSizedInline—Minimum inline size.
overflowOverflow—CSS overflow.
overflowBlockOverflow—Block-axis overflow when the shorthand is not enough.
overflowInlineOverflow—Inline-axis overflow when the shorthand is not enough.
paddingSpacing—Padding from the space scale, on all sides or per logical side.
positionPosition—CSS position.
refRef<BoxHost<T>>—Ref to the rendered element.
regionClassCssModuleClass—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.
shrinkboolean—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.
stateStateAttributesInput—Design-system state attributes. Raw data-* state names are reserved.
titleLocalizedMessage | DisplayValue—Native tooltip; accessibility hint, not visible UI title text.
widthSizedInline—Inline size. Replaces ui-core's free-form width.
zIndexZIndex—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
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: no descendants, :global, :has(), or design-system data-* hooks.
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.
FlexItemCSS equivalentNotes
Fixedflex: 0 0 autoNon-growing chrome
Fillflex: 1 1 autoDefault flex child
FillZeroBasisflex: 1 1 0Equal flex siblings
FillNoShrinkflex: 1 0 autoMain pane that must not shrink below content width
FillScrollflex: 1 1 0 + min-height/min-width: 0 + overflow: autoScroll host inside a sized flex column (BX-3)
grow, shrink, and basis remain available for one-off tuning; avoid combining conflicting overrides with item.
alignSelf
AlignSelfMaps to
Startalign-self: flex-start
Endalign-self: flex-end
Centeralign-self: center
Baselinealign-self: baseline
Stretchalign-self: stretch
Before and after
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.
  1. Use FlexBox for Layouts
    • Prefer FlexBox over Box display={Display.Flex} for flex layouts
    • Use gap prop for consistent spacing between flex items
  2. Responsive Design
    • Use relative units for width/height when possible
    • Consider using grow and shrink for flexible layouts
  3. Performance
    • Box components are memoized for better performance
    • Avoid unnecessary nesting of Box components
  4. Accessibility
    • Use semantic HTML elements when possible
Common Patterns
Card Pattern
Previous
Box / Usage
Next
Circle / Usage
On this page
Basic Usage
Props
Layout
FlexBox
Spacing
Positioning
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
className
regionClass
Flex item (item)
alignSelf
Before and after
Flex column fill and scroll
Best Practices
Common Patterns
Card Pattern