@spark-web/box

title: Box storybookPath: page-layout-box--default isExperimentalPackage: false

The Box component is our lowest-level primitive. The goal of the Box component is to map props to our tokens so that consumers should be able to use these props for all of their styling needs. Ideally, you shouldn't need to use the className or style prop at all. Internally, all Spark Web components are composed using the Box component.

Box is a polymorphic component (meaning it will render different elements depending on what is provided to the as prop). If no as prop is provided, Box will render a div.

We also spread in consumer props, so any valid HTML attributes are also valid for Box. Due to some clever TypeScript we can even warn you when you use an invalid combination of props.

<Box as="input" href="https://spark.brighte.com.au" />

In the example above, you should see a "red squiggly" under the href element with the following error:

Type '{ as: "input"; href: string; }' is not assignable to type 'IntrinsicAttributes & { as?: "input" | undefined; ref?: Ref<HTMLInputElement> | undefined; } & Omit<Pick<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" | keyof InputHTMLAttributes<...>>, "as"> & { ...; } & UnresponsiveBoxProps & ResponsiveBoxProps'.
  Property 'href' does not exist on type 'IntrinsicAttributes & { as?: "input" | undefined; ref?: Ref<HTMLInputElement> | undefined; } & Omit<Pick<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" | keyof InputHTMLAttributes<...>>, "as"> & { ...; } & UnresponsiveBoxProps & ResponsiveBoxProps'. Did you mean 'ref'?

Unfortunately TypeScript errors can be pretty cryptic sometimes 🙃.

Pro tip: copying the error message and pasting it into TypeScript Error Translator can sometimes help make these errors easier to understand.

A minimal CSS reset is also applied to each element rendered with Box. This helps prevent styles from "leaking" out and effecting other elements (which should make it easier to incrementally adopt Spark Web into existing projects). If you provide a non-Spark component to the as prop instead of an element, it is recommended that you also use the asElement prop so the appropriate styles can be applied.

Examples

Responsive styles

Most of Box's props accept a string value (usually corresponding to a token), we also accept an object for responsive styles.

const items = [1, 2, 3];

return (
  <Box
    background="primaryLow"
    display="inline-flex"
    flexDirection={{ mobile: 'row', tablet: 'column', desktop: 'rowReverse' }}
    gap={{ mobile: 'small', tablet: 'medium', desktop: 'large' }}
    padding={{ mobile: 'small', tablet: 'medium', desktop: 'large' }}
  >
    {items.map(item => (
      <Row
        key={item}
        align="center"
        alignY="center"
        background="primary"
        height={{ mobile: 'small', tablet: 'medium', desktop: 'large' }}
        width={{ mobile: 'small', tablet: 'medium', desktop: 'large' }}
      >
        <Text>{item}</Text>
      </Row>
    ))}
  </Box>
);

Resize your browser to see the example above change at different breakpoints.

Backgrounds

Box stores the background in a provider. We can use this to work out what colour to use by default for text elements.

const backgroundTones = [
  // Light
  ['surface', 'positiveLight', 'infoLight', 'cautionLight', 'criticalLight'],
  // Dark
  ['muted', 'positive', 'info', 'caution', 'critical'],
];

return (
  <Stack gap="large">
    {backgroundTones.map((backgrounds, index) => (
      <Columns
        key={index}
        collapseBelow="tablet"
        gap="large"
        template={[1, 1, 1]}
      >
        {backgrounds.map(background => (
          <Box
            key={background}
            shadow="medium"
            background={background}
            height="large"
            display="flex"
            flexShrink={0}
            alignItems="center"
            justifyContent="center"
          >
            <Text weight="semibold">{background}</Text>
          </Box>
        ))}
      </Columns>
    ))}
  </Stack>
);

Notice that the Text in the example above doesn't use the tone prop, the colour is worked out using the BackgroundProvider in Box.

Note: this will only work if you use the background prop. If you try to style the background colour in any other way the Text component will not know what colour the background is and so cannot invert its colour to make sure that its contents are readable.

<Box style={{ background: 'midnightblue' }} padding="large">
  <Text>Good luck reading this!</Text>
</Box>

Props

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