Box

Box is a styled div built with styled-components and styled-system. Use it for layout, spacing, surfaces and any container that needs theme-aware styles. Every other element (Text, Button, Field) extends it, so the props on this page are available everywhere.

Import#

import { Box } from "@reactberry/system/elements";

Usage#

import { Box, Text } from "@reactberry/system/elements";

export default function StatCard() {
  return (
    <Box display="flex" flexDirection="column" gap="xs" p="m" skin="card" shape="rounded" $shadow="small">
      <Text fontSize="s" color="secondary">Monthly revenue</Text>
      <Text fontSize="xl" fontWeight="600">$48,250</Text>
    </Box>
  );
}

Examples#

Skins and shapes#

skin applies a background, border colour and text colour from theme.skins; shape sets the border radius from theme.shapes.

Interactive states#

hover and focus take a skin path. For raw styles per state, use interactive.

Responsive layout#

Style props accept arrays or breakpoint objects. This row stacks on narrow screens.

API#

Box#

Box also accepts these styled-system groups. Values resolve against the theme where a scale exists, otherwise they pass through as raw CSS. All of them accept arrays or breakpoint objects; breakpoint keys are xs, sm, md, lg and xl, with _ as the base.

• color — color, bg / backgroundColor, opacity; maps to theme.colors
• space — m, p and their directional variants (mt, px, and so on); maps to theme.space
• layout — width, height, minWidth, maxWidth, size, display, overflow, verticalAlign; size maps to theme.sizes
• flexbox — alignItems, justifyContent, flexDirection, flex, flexWrap, order, and related props
• grid — gridTemplateColumns, gridArea, gridGap, and related props
• position — position, top, right, bottom, left, zIndex
• background — backgroundImage, backgroundSize, backgroundPosition, backgroundRepeat
• border — border, borderColor, borderWidth, borderRadius, and directional variants
• shadow — boxShadow, textShadow

Other props, such as id, role and event handlers, are passed to the rendered element.

Theme tokens#

Space aliases (theme.space):

• mini 0.125rem, xxxs 0.25rem, xxs 0.375rem, xs 0.5rem, s 0.75rem, m 1rem, l 1.5rem, xl 2rem, xxl 2.5rem, xxxl 3rem
• Long names (xsmall, small, medium, large, xlarge) match the short ones; xxlarge is 3rem and xxxlarge is 4rem

Size aliases for size (theme.sizes):

• xs 0.5rem, s 0.75rem, m 1rem, l 1.125rem, xl 1.25rem

Shapes (theme.shapes):

• square 0px, roundedSmall 4px, rounded 8px, roundedLarge 16px, pill 32px, circle 50%
• roundedTop, roundedBottom, roundedLeft, roundedRight round one side by 6px

Control sizes for $size (theme.controlSizes):

• xxxsmall — height 1.5rem, padding 0.125rem 0.5rem
• xxsmall — height 1.75rem, padding 0.125rem 0.5rem
• xsmall — height 2rem, padding 0.25rem 0.75rem
• small — height 2.25rem, padding 0.25rem 0.75rem
• medium — height 2.5rem, padding 0.5rem 1rem
• large — height 3rem, padding 0.5rem 2rem
• xlarge — height 4rem, padding 0.5rem 2.5rem

Shadows for $shadow (theme.shadows):

• xxsmall, xsmall, small, medium, large

Skins#

Skins resolve by dot path, so nested entries are available as card.shade or translucent.dark. The default light theme includes:

• Surfaces — base, surface, panel, card, overlay, each with .shade and .tint
• Signals — error, success, warning, info, brand, accent, neutral, signal, each with .static, .interactive and .subtle entries (for example error.static); brand and accent also have .light
• Colour pairs — red, orange, yellow, green, teal, blue, purple, pink, gray, primary
• States — highlight, focused, minimal, outlined (with .success)
• Special — transparent, translucent (with .light, .dark, .yellow), gradient, contrast
• Hover — hover.default, hover.subtle, hover.dim, hover.brand, hover.error, hover.info, hover.warning, hover.success, hover.contrast, hover.lighten, hover.accent

The dark theme defines a smaller set. Check src/themes/default/modes/dark/skins.js before relying on a specific key.

Accessibility#

• Box renders a plain div with no role. Pass as (for example as="section" or as="nav") for semantic elements.
• focus styles only show on focusable elements. Add tabIndex={0} to a div that should receive focus.

Notes#

• Box does not apply typography props such as fontSize, fontWeight or lineHeight. Use Text for those.
• Use size (or width / height) for dimensions. $size applies control height and padding.
• Most signal skins, such as error, only define nested entries, so use a leaf path like error.static rather than error alone.
• Prefer theme aliases (p="m") over raw values (p="16px").