Box is the lowest-level component for binding theme-based styles to an individual element on the screen. Internally, all Balance components are made up of Boxes.

Semantic elements

By default, Box renders a div element. You can customise this via the as prop. Non-Balance props will be forwarded to the underlying element.

<Box as="span" aria-hidden>
  ...
</Box>

Usage

Padding

The padding keys allow targeting each side as well as the x-axis and y-axis.

padding
paddingTop
paddingRight
paddingBottom
paddingLeft
paddingX padding-left and padding-right
paddingY padding-top and padding-bottom

Edit in Playroom

<Box padding="medium" background="dim">
  <Text>padding</Text>
</Box>

Margin

The margin keys allow targeting each side as well as the x-axis and y-axis.

margin
marginTop
marginRight
marginBottom
marginLeft
marginX margin-left and margin-right
marginY margin-top and margin-bottom

Edit in Playroom

<Box margin="medium" background="dim">
  <Text>margin</Text>
</Box>

Border

Apply a border to the box:

Edit in Playroom

<Columns gap="large">
  <Box border="standard" padding="small">
    <Text>standard</Text>
  </Box>
  <Box border="standard" borderWidth="large" padding="small">
    <Text>large</Text>
  </Box>
  <Box border="muted" padding="small">
    <Text>muted</Text>
  </Box>
</Columns>

Border radius

Apply a border-radius to the box:

Edit in Playroom

<Inline gap="large">
  <Box borderRadius="xsmall" background="dim" height={44} width={44} />
  <Box borderRadius="small" background="dim" height={44} width={44} />
  <Box borderRadius="medium" background="dim" height={44} width={44} />
  <Box borderRadius="large" background="dim" height={44} width={44} />
</Inline>

Box shadow

Apply a box-shadow to the box:

Edit in Playroom

<Inline gap="large">
  <Box boxShadow="xsmall" borderRadius="small" height={44} width={44} />
  <Box boxShadow="small" borderRadius="small" height={44} width={44} />
  <Box boxShadow="medium" borderRadius="small" height={44} width={44} />
  <Box boxShadow="large" borderRadius="small" height={44} width={44} />
  <Box boxShadow="xlarge" borderRadius="small" height={44} width={44} />
</Inline>

Height

Apply a height to the box:

Edit in Playroom

<Box height={50} background="dim" padding="small">
  <Text>50px tall</Text>
</Box>

Width

Apply a width to the box:

Edit in Playroom

<Box width={200} background="dim" padding="small">
  <Text>200px wide</Text>
</Box>

Combined

Mix and match style properties to achieve the desired aesthetic.

Edit in Playroom

<Box
  background="dim"
  borderRadius="small"
  margin="small"
  paddingX="large"
  paddingY="medium"
  width={200}
>
  <Text>Combined</Text>
</Box>

Responsive Props

Instead of manually managing media queries and adding nested style objects throughout a code base, we offer a convenient shorthand syntax for adding responsive styles with a mobile-first approach.

Each of the above style props accepts a value or array of values. To skip certain breakpoints, you can pass null to any position in the array to avoid generating unnecessary CSS.

While this approach has been widely adopted with great success, much like any new idea, it can seem odd or off-putting at first. We recommend giving it a chance.

Edit in Playroom

<Box background="dim" padding={['small', null, 'medium', 'none', 'large']}>
  <Text>responsive props</Text>
</Box>