Skip to main content

Box

The <Box /> component is the smallest primitive available. It is used by many of the design system components behind the scenes and gives full flexibility for constructing complex UIs.

It also surfaces the styling API through atoms which can be specified as props. For more, see styling.

Examples

Box

Simple usage. By default this usage renders a <div>.

I'm a box
Code
<Box>
  I'm a box
</Box>

Polymorphism

<Box> is polymorphic, meaning it can be rendered as any HTML element.

I'm a box that's a span
Code
<Box as="span">
  I'm a box that's a span
</Box>

Styling Box

The <Box> component has full access to all styling that the design system permits via "atom" props. The available options are listed in the "props" table below. For more, see styling.

Code
<Box
  atoms={{
    backgroundColor: 'notification-positive',
    padding: {
      desktop: '32px',
      mobile: '20px'
    }
  }}
 />

Themes

The <Box> component has different color themes, which can be configured by passing a theme prop. Please be aware that some themes can cause accessibility issues when used in combination with small font sizes.

light theme (default)

Some text with a link

rebrand theme

Some text with a link

dark theme

Some text with a link

brand theme

Some text with a link

Code
<Stack gap="8px">
  <Box
    atoms={{
      backgroundColor: 'global-default',
      border: 'default',
      padding: '16px'
    }}
    theme="light"
  >
    <Heading level={4}>
      light theme (default)
    </Heading>
    <Text size="lg">
      Some text with a{' '}
      <Link
        href="/"
        inline
      >
        link
      </Link>
    </Text>
  </Box>
  <Box
    atoms={{
      backgroundColor: 'global-default',
      border: 'default',
      padding: '16px'
    }}
    theme="rebrand"
  >
    <Heading level={4}>
      rebrand theme{' '}
    </Heading>
    <Text size="lg">
      Some text with a{' '}
      <Link
        href="/"
        inline
      >
        link
      </Link>
    </Text>
  </Box>
  <Box
    atoms={{
      backgroundColor: 'global-default',
      border: 'default',
      padding: '16px'
    }}
    theme="dark"
  >
    <Heading level={4}>
      dark theme{' '}
    </Heading>
    <Text size="lg">
      Some text with a{' '}
      <Link
        href="/"
        inline
      >
        link
      </Link>
    </Text>
  </Box>
  <Box
    atoms={{
      backgroundColor: 'global-default',
      border: 'default',
      padding: '16px'
    }}
    theme="brand"
  >
    <Heading level={4}>
      brand theme{' '}
    </Heading>
    <Text size="lg">
      Some text with a{' '}
      <Link
        href="/"
        inline
      >
        link
      </Link>
    </Text>
  </Box>
</Stack>

Input Ref

Passing an inputRef.

I'm a box with a yellow background
Code
<Box
  inputRef={{
    current: '[Circular]'
  }}
>
  I'm a box with a yellow background
</Box>

Props

as

ElementType<any, keyof IntrinsicElements>

theme

Theme

loading

"eager" | "lazy"

Not included in `AllHTMLAttributes` yet so sourced from https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img

decoding

"auto" | "sync" | "async"

Not included in `AllHTMLAttributes` yet so sourced from https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img

inputRef

Ref<HTMLElement>

Has to not be called ref - done because we also want to use a generic see https://gist.github.com/gaearon/1a018a023347fe1c2476073330cc5509