React Box component

Preview

<Box plane="band" radius="control" inset="compact">
  Recessed strip on the band plane
</Box>

Usage

Use when

Putting a region on a named plane: canvas, band, surface or raised
A hairline-separated strip or a bordered region without Card's header and footer
Rendering a semantic element with the surface inset

Avoid when

Spacing a row or column of siblings (use Stack)
Two-dimensional layouts (use Grid)
Header/body/footer surfaces (use Card)
Ink and type (use Text)
Scrolling regions (use ScrollArea)
State callouts (use Alert)
Lifting a box with a shadow: only floating surfaces cast shadow

Implementation notes

Pick the plane by role, never by colour: canvas is the page floor, band a recessed strip, surface the card plane, raised a lifted plane
Use radius="nested" for a box inside a surface so the corners stay concentric
Parent owns spacing: put Boxes in a Stack with a gap instead of adding margins
Size a Box with className when it must be fixed; the props carry no raw dimensions

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

Surface

A bordered region on the surface plane.

<Box plane="surface" border radius="surface" inset="default">
  Bordered region on the surface plane
</Box>

Nested

A band tile inside a surface keeps its corners concentric.

import { Box } from '@usefragments/ui';

<Box plane="surface" border radius="surface" inset="compact">
  <Box plane="band" radius="nested" inset="compact">
    Inner tile at the nested corner
  </Box>

Block Border

A single hairline on one logical side divides two strips.

<Box border="block-end" inset="compact">
  Hairline below only
</Box>

Planes

The four planes side by side.

import { Box } from '@usefragments/ui';
import { Stack } from '@usefragments/ui';

<Box plane="canvas" inset="default">
  <Stack gap="sm">
    <Box plane="band" radius="control" inset="compact">Band</Box>

API reference

Component props
Prop	Type	Default	Description
`as`	`"div" \| "article" \| "aside" \| "footer" \| "header" \| "main" \| "nav" \| "section" \| "span" \| undefineddivarticleasidefooterheadermainnavsectionspan`	`div`	HTML element to render
`border`	`BoxBorder \| undefined`	Not set	The one hairline: true on every side, or a single logical block side.
`children`	`React.ReactNode`	Not set	Content to render inside the box
`inset`	`BoxInset \| undefineddefaultnonecompact`	Not set	Inner inset from the surface inset recipe: compact (12) or default (16).
`plane`	`BoxPlane \| undefinedcanvasbandsurfaceraised`	Not set	The plane the box paints: canvas (page floor), band (recessed strip), surface (card plane) or raised (lifted plane). Omit for a transparent box.
`radius`	`BoxRadius \| undefinednonenestedsurfacecontrol`	Not set	Corner role. nested is the concentric corner for a box inset inside a surface.
`className`	`string \| undefined`	Not set	Additional class; use it for one-off sizing

Accessibility

Choose a semantic as value (section, aside, nav) for landmark regions
A plane is decoration: never let it carry meaning on its own

StackalternativeUse Stack for directional layouts with gap
GridalternativeUse Grid for column-based layouts
CardalternativeUse Card for content containers with structure

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.