Skip to main content

Box

Box is Tosui's layout and styling primitive. It accepts a constrained set of style props and renders a div by default.

Open in Storybook

Import​

import { Box } from "@tosui/react";

Basic usage​

Polymorphic rendering​

The as prop changes the rendered HTML element. TypeScript derives native attributes and the ref type from the selected element.

<Box as="section" p={6}>
  Section content
</Box>

<Box as="article" bg="surface">
  Article content
</Box>

<Box as="nav">
  Navigation items
</Box>

Spacing​

Box supports Tosui's multiplier-based spacing system (4px base unit):

Padding​

All sides: 16px

Horizontal: 24px, Vertical: 12px

Top: 8px, Bottom: 16px

Padding props: p, px, py, pt, pr, pb, pl

Margin​

<Box m={4}>All sides: 16px</Box>
<Box mx={6} my={3}>Horizontal: 24px, Vertical: 12px</Box>
<Box mt={2} mb={4}>Top: 8px, Bottom: 16px</Box>

Margin props: m, mx, my, mt, mr, mb, ml

Layout​

Display​

<Box display="flex">Flexbox container</Box>
<Box display="grid">Grid container</Box>
<Box display="block">Block element</Box>
<Box display="inline">Inline element</Box>

Position​

<Box position="relative">Relative positioning</Box>
<Box position="absolute" top={0} left={0}>Absolute positioning</Box>
<Box position="fixed" bottom={4} right={4}>Fixed positioning</Box>

Sizing​

<Box w="100%">Full width</Box>
<Box h="200px">Fixed height</Box>
<Box minW="300px" maxW="600px">Constrained width</Box>

Size props: w, h, minW, maxW, minH, maxH

Flexbox​

Box accepts these flexbox props:

Item 1
Item 2
Left
Right

Flexbox props: flexDirection, justifyContent, alignItems, alignSelf, flexWrap, gap, gapRow, gapColumn, flex, flexGrow, flexShrink, flexBasis

Grid​

<Box display="grid" gridTemplateColumns="1fr 1fr 1fr" gap={4}>
  <Box>Column 1</Box>
  <Box>Column 2</Box>
  <Box>Column 3</Box>
</Box>

Grid props: gridTemplateColumns, gridTemplateRows, justifySelf

Colors​

Tosui uses semantic color tokens that adapt to light and dark themes. The color, bg, and borderColor props accept different token sets.

<Box bg="surface" color="foreground">
  Default text on surface background
</Box>

<Box bg="primary-default" color="foreground-inverted">
  Primary colored box
</Box>

<Box borderColor="border" border="thin">
  Box with border
</Box>

Color props: color, bg, borderColor

Borders​

All borders

Left border accent

Dashed top and bottom borders

Border props: border, borderX, borderY, borderTop, borderRight, borderBottom, borderLeft, borderStyle

Border widths: none, thin (1px), medium (2px), thick (4px)

Roundness​

Standard rounded corners

Sharp top-left corner

Pill shape

Roundness props: rounded, roundedTop, roundedBottom, roundedLeft, roundedRight, roundedTopLeft, roundedTopRight, roundedBottomLeft, roundedBottomRight

Values: none, sm, md, lg, full

Shadows​

Subtle elevation

Card with medium elevation

Modal with high elevation

Shadow props: shadow

Values: none, sm, md, lg

Typography​

While Box supports typography props, consider using the Text or Heading components for text content:

<Box fontSize="lg" fontWeight="semibold">
  Large semibold text
</Box>

Typography props: fontSize, fontFamily, fontWeight, lineHeight, textAlign, whiteSpace

Interactions​

<Box cursor="pointer" userSelect="none">
  Clickable element
</Box>

<Box pointerEvents="none">
  Non-interactive overlay
</Box>

Interaction props: cursor, pointerEvents, userSelect

Overflow​

<Box overflow="hidden">
  Clipped content
</Box>

<Box overflowY="scroll" maxH="300px">
  Scrollable content
</Box>

Overflow props: overflow, overflowX, overflowY

Opacity​

<Box opacity="faint">
  40% opacity
</Box>

<Box opacity="semi">
  60% opacity
</Box>

Opacity values are invisible (0), faint (0.4), semi (0.6), and full (1).

Combined example​

The following example combines layout and style props:

<Box
  as="article"
  bg="surface"
  p={6}
  rounded="lg"
  shadow="md"
  border="thin"
  borderColor="border"
  display="flex"
  flexDirection="column"
  gap={4}
>
  <Box as="h2" fontSize="2xl" fontWeight="semibold">
    Card Title
  </Box>
  <Box color="foreground-muted">Card content with muted text</Box>
</Box>

Props reference​

Box accepts all props from its constituent style parts:

  • Spacing: Margin and padding with multiplier values (0-32)
  • Layout: Display, position, overflow, z-index
  • Size: Width, height, and their min/max variants
  • Flexbox: Direction, alignment, wrapping, gaps, and flex sizing
  • Grid: Grid template and positioning
  • Inset: Positioning offsets (top, right, bottom, left)
  • Typography: Font properties and text styling
  • Colors: Semantic color tokens
  • Borders: Border width, style, and directional control
  • Roundness: Border radius with directional control
  • Shadows: Elevation levels
  • Interactions: Cursor, pointer events, user selection
  • Opacity: Transparency control

TypeScript​

import { Box, type BoxOwnProps, type BoxProps } from "@tosui/react";

BoxProps<T> includes the native attributes for element type T. BoxOwnProps contains only the props defined by Tosui.