Box

On this page

Vessel notes

A small inset around this note.

This note has no extra inset.

The primitives composed: every value a token's name, never a raw color or distance.

Code

import { Box } from "@bosunkit/components/box";
import { Stack } from "@bosunkit/components/stack";
import { Text } from "@bosunkit/components/text";
import { Heading } from "@bosunkit/components/heading";
import type { ReactElement } from "react";

export const description: string =
  "The outer box owns its inset. Nested boxes use their own padding, and the stack separates the notes.";

export default function Example(): ReactElement {
  return (
    <Box background="surface2" padding="lg" paddingInline="xl" radius="md">
      <Stack space="md">
        <Heading level={2} variant="heading-component">Vessel notes</Heading>
        <Box background="surface" padding="xs">
          <Text>A small inset around this note.</Text>
        </Box>
        <Box background="surface">
          <Text>This note has no extra inset.</Text>
        </Box>
      </Stack>
    </Box>
  );
}

Box is one of the layout primitives the pages are built from. Its props take the scales by name — a spacing prop a step of the spacing scale, a color prop a semantic token — and each becomes a class or a custom property on the element, never a stylesheet. Every primitive takes as, the element to render, and testId.

Padding belongs to this box. An omitted padding prop adds no inset, including inside another box. paddingBlock and paddingInline override padding on their own axes and apply only to this box. Use Stack or Inline for space between siblings.

Vessel notes

A small inset around this note.

This note has no extra inset.

The outer box owns its inset. Nested boxes use their own padding, and the stack separates the notes.

Code

import { Box } from "@bosunkit/components/box";
import { Stack } from "@bosunkit/components/stack";
import { Text } from "@bosunkit/components/text";
import { Heading } from "@bosunkit/components/heading";
import type { ReactElement } from "react";

export const description: string =
  "The outer box owns its inset. Nested boxes use their own padding, and the stack separates the notes.";

export default function Example(): ReactElement {
  return (
    <Box background="surface2" padding="lg" paddingInline="xl" radius="md">
      <Stack space="md">
        <Heading level={2} variant="heading-component">Vessel notes</Heading>
        <Box background="surface" padding="xs">
          <Text>A small inset around this note.</Text>
        </Box>
        <Box background="surface">
          <Text>This note has no extra inset.</Text>
        </Box>
      </Stack>
    </Box>
  );
}

Own the inset once

Use Box to establish a surface and its inner padding. Use Stack or Inline to separate its children. Adding padding to every nested box makes the reading edge drift; choose which container owns the inset and leave inner boxes unpadded unless they represent a separate region.

Select as for document meaning, not appearance. A visual box is not automatically a named section, a card heading or an interactive target. Use Card when its title, actions and footer are needed. On narrow screens, allow children to reflow inside the inset and keep their focus rings visible.

Props

Prop	Type	Default	Description
childrenrequired	ReactNode	–	The box's content.
background	ColorToken \| undefined	–	The background, a semantic color token by name; none unless set.
color	ColorToken \| undefined	–	The text color, a semantic color token by name; the text token unless set.
padding	SpaceScale \| undefined	–	The padding on every side, a step of the spacing scale by name.
paddingBlock	SpaceScale \| undefined	–	The padding on the block axis, a step of the spacing scale by name.
paddingInline	SpaceScale \| undefined	–	The padding on the inline axis, a step of the spacing scale by name.
radius	RadiusScale \| undefined	–	The corner radius, a step of the radius scale by name.
as	PrimitiveElement \| undefined	"div"	The element to render; `div` unless set.
className	string \| undefined	–	Classes added to the element's own.
testId	string \| undefined	–	Becomes `data-testid` on the element.