Orbit

Box

Source

The polymorphic, token-driven layout and style primitive. Box compiles typed props into StyleX styles at build time, tokens auto-resolve light and dark mode, and display defaults to flex.

Overview

Box is the canonical primitive for layout, spacing, color, borders, radius, shadow, flex, grid, position and motion.

Every visual concern is a typed prop that accepts a design token, so there is no className guesswork and no dark mode boilerplate. Props take token names rather than raw values, and any prop also accepts a responsive or pseudo-state object.

Box defaults to display flex for block-level elements, so a bare Box is a flex row. Set flexDirection, gap and alignment directly without repeating display. Inline elements and li keep their native display.

Layout

Compose flex layouts with direction, alignment and token-based gaps.

Vertical stack

flexDirection column with a rowGap token.

First

Second

Third

<Box flexDirection="column" rowGap="m">
  <Tile>First</Tile>
  <Tile>Second</Tile>
  <Tile>Third</Tile>
</Box>

Centered row

The default flex row, centered with a columnGap token.

One

Two

Three

<Box alignItems="center" columnGap="m">
  <Tile>One</Tile>
  <Tile>Two</Tile>
  <Tile>Three</Tile>
</Box>

Spacing and color

Surfaces are built by composing radius, background, border and padding tokens.

Card surface

Radius, background, border and padding composed from tokens.

<Box
  borderRadius="l"
  backgroundColor="background-card"
  borderWidth={1}
  borderStyle="solid"
  borderColor="border-primary"
  padding="xl"
  flexDirection="column"
  rowGap="m"
>
  <Text variant="heading-xxs" as="h4">Card surface</Text>
  <Text color="default">Radius, background, border and padding from tokens.</Text>
</Box>

Polymorphism

The as prop selects the underlying element for correct semantics and accessibility, while keeping the same typed style API.

List item rendered as li
Keeps native list-item display

<Box as="nav" alignItems="center" columnGap="m">
  <Text variant="label">Home</Text>
  <Text variant="label" color="default">Docs</Text>
</Box>

<Box as="ul" flexDirection="column" rowGap="s">
  <Box as="li">List item rendered as li</Box>
</Box>

Responsive and pseudo-states

Any style prop accepts an object keyed by base, the breakpoints and the pseudo-states hover, focus and active. Pair with a transition to animate.

Interactive card

Hover me

Pseudo-state props animate background, shadow and transform.

<Box
  borderRadius="l"
  backgroundColor={{ base: 'background-card', hover: 'background-secondary' }}
  boxShadow={{ base: 's', hover: 'm' }}
  transform={{ hover: 'translateY(-2px)' }}
  transitionProperty="common"
  transitionDuration="fast"
  ease="decelerate"
  cursor={{ hover: 'pointer' }}
  padding="xl"
>
  …
</Box>

Escape hatches

Box accepts className and style for things outside the design system.

Reach for className or style only for concerns the system does not model, such as animation keyframes or third-party utility classes. Never use them to re-implement a property that already has a typed prop. If you write className with a padding or background utility, you are using Box wrong.