Box | Fragments

Preview

<Box padding="md" background="secondary" rounded="md">
  Content with padding and background
</Box>

Installation

npx @usefragments/cli add box

Writes src/fragments/ui/components/Box plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Examples

With Border

A hairline border instead of a filled background.

<Box padding="lg" border rounded="md">
  Bordered content area
</Box>

Directional Padding

Horizontal and vertical padding set separately.

<Box paddingX="xl" paddingY="sm" background="tertiary" rounded="sm">
  Wide horizontal padding, short vertical
</Box>

Centered with Auto Margin

marginX="auto" centres a fixed-width box in a wider parent.

import { Box } from '@/components/Box';

<Box width="100%" border rounded="md" padding="md">
  <Box padding="md" marginX="auto" width="240px" background="elevated" rounded="lg">
    Centred by auto margin
  </Box>

Directional Borders

Border on chosen sides only.

<Box padding="md" borderTop borderBottom>
  Top and bottom borders only
</Box>

With Shadow

Shadow lifts the surface off the page.

<Box padding="lg" rounded="md" shadow="md" background="primary">
  Elevated content with shadow
</Box>

Overflow Hidden

Content past the box's height is clipped, not scrolled.

import { Box } from '@/components/Box';

<Box padding="md" overflow="hidden" border rounded="md" width="320px" height="72px">
  This box clips its overflowing content. Lorem ipsum dolor sit amet, consectetur
  adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna
  aliqua, and this final sentence never becomes visible.

Text Colors

Text colour tokens, from strongest to accent.

import { Box } from '@/components/Box';
import { Stack } from '@/components/Stack';

<Stack direction="row" gap="md">
  <Box color="primary">Primary</Box>
  <Box color="secondary">Secondary</Box>

API

Component props
Prop	Type	Default	Description
`children`	`node`	Not set	Content to render inside the box
`as`	`enumdivsectionarticleasidemainheaderfooternavspan`	`div`	HTML element to render
`padding`	`enumnonexssmmdlgxl`	Not set	Padding on all sides
`paddingX`	`enumnonexssmmdlgxl`	Not set	Horizontal padding
`paddingY`	`enumnonexssmmdlgxl`	Not set	Vertical padding
`margin`	`enumnonexssmmdlgxlauto`	Not set	Margin on all sides
`marginX`	`enumnonexssmmdlgxlauto`	Not set	Horizontal margin
`marginY`	`enumnonexssmmdlgxlauto`	Not set	Vertical margin
`background`	`enumnoneprimarysecondarytertiaryelevated`	Not set	Background color
`rounded`	`enumnonesmmdlgfull`	Not set	Border radius
`border`	`boolean`	`false`	Show border
`borderTop`	`boolean`	`false`	Show top border only
`borderBottom`	`boolean`	`false`	Show bottom border only
`borderLeft`	`boolean`	`false`	Show left border only
`borderRight`	`boolean`	`false`	Show right border only
`borderColor`	`enumdefaultstrongaccentdanger`	Not set	Border color variant (requires border or directional border)
`shadow`	`enumnonesmmdlg`	Not set	Box shadow
`overflow`	`enumhiddenautoscrollvisible`	Not set	Overflow behavior
`color`	`enumprimarysecondarytertiaryaccentinverse`	Not set	Text color
`display`	`enumnoneblockinlineinline-blockflexinline-flexgrid`	Not set	Display type
`width`	`union`	Not set	Width (CSS value, e.g. "100%", "300px", or number for px)
`minWidth`	`union`	Not set	Min width
`maxWidth`	`union`	Not set	Max width
`height`	`union`	Not set	Height (CSS value)
`minHeight`	`union`	Not set	Min height
`maxHeight`	`union`	Not set	Max height
`className`	`string`	Not set	Additional class name
`style`	`object`	Not set	Inline styles

Accessibility

Choose semantic as prop values for proper document structure
Avoid div-soup; use meaningful elements like section, article
Ensure proper heading hierarchy within Box containers

Guidance

Use when

Padding or insetting a section of content
Bordered or elevated containers
Rendering a semantic element with design-system spacing

Avoid when

Spacing a row or column of siblings (use Stack)
Two-dimensional layouts (use Grid)
Header/body/footer surfaces (use Card)
Styling text alone (use Text)

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

Next steps

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