Concepts

The “as” prop

Most components in Balance accept the as prop, which allows you to change the root element that the component renders.

For instance, <Box as="span" /> would render the Box component as a span tag instead of its default (in this case, div).

Important: Changing the root element can affect the styles and accessibility of a component. Consider how the component will be used when specifying the as prop.

Layout

Balance components do not provide surrounding white space. Instead, spacing between elements is owned entirely by layout primitives. This approach ensures that the system is as composable as possible while keeping white space predictable.

The layout primitives below can be nested within each other to create a wide variety of layouts. Getting a firm grasp of these layout primitives is an essential part of working effectively with Balance.

Spacing

Balance provides a standard spacing scale that is used by the layout primitives.

Box

Box is the most low-level layout primitive provided by Balance. Its job is to render an individual element on the screen.

In terms of page layout, Box most notably provides a set of padding options which can be used to create container elements with internal spacing.

These options accept a value from the spacing scale. For example, if you wanted to create a container element with small spacing on all sides:

<Box padding="small">
  <Text>Lorem ipsum dolor sit amet.</Text>
</Box>

These also support the ‘responsive props’ format which allows you to specify a set of values for different screen sizes.

For example, if you wanted small spacing on mobile but medium spacing from tablet upwards:

<Box padding={['small', 'medium']}>
  <Text>Lorem ipsum dolor sit amet.</Text>
</Box>

Stack

The most common white space on screen is between elements stacked vertically. For this use case, Balance provides a Stack component that accepts a ‘gap’ prop.

For example, if you wanted to render a stack of Heading and Text elements with large spacing between them:

<Stack gap="large">
  <Heading level="4">Heading</Heading>
  <Text>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
    dignissim dapibus elit, vel egestas felis pharetra non.
  </Text>
  <Text>
    Phasellus ipsum tortor, aliquet dapibus fermentum, mollis vel metus.
    Vestibulum malesuada ante eu velit malesuada, nec ultricies sapien.
  </Text>
</Stack>

To visually break up content, you can insert dividers between all stack elements by setting the dividers prop on Stack:

<Stack gap="large" dividers>
  <Heading level="4">Heading</Heading>
  <Text>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
    dignissim dapibus elit, vel egestas felis pharetra non.
  </Text>
  <Text>
    Phasellus ipsum tortor, aliquet dapibus fermentum, mollis vel metus.
    Vestibulum malesuada ante eu velit malesuada, nec ultricies sapien.
  </Text>
</Stack>

Multiple Stack components can be nested to create more complex white space rules. For example, if you wanted to group blocks of text:

<Stack gap="large">
  <Heading level="5">Heading</Heading>
  <Stack gap="xsmall">
    <Text>Line 1</Text>
    <Text>Line 2</Text>
    <Text>Line 3</Text>
  </Stack>
  <Stack gap="xsmall">
    <Text>Line 1</Text>
    <Text>Line 2</Text>
    <Text>Line 3</Text>
  </Stack>
</Stack>

Stack also supports alignment. For example, if you wanted to centre align all content within a Stack:

<Stack gap="medium" align="center">
  <StarIcon color="informative" />
  <Badge weight="bold" tone="informative" label="Badge" />
  <Heading level="5">Heading text</Heading>
  <Text color="muted">Lorem ipsum dolor sit amet.</Text>
</Stack>

Inline

If you’d like to render a set of components in a row with equal spacing around them, wrapping onto multiple lines when necessary, Balance provides a Inline component:

<Inline gap="small">
  <Tag label="Lorem ipsum" />
  <Tag label="Dolor" />
  <Tag label="Sit amet" />
  <Tag label="Consectetur" />
  <Tag label="Adipiscing elit" />
  <Tag label="Suspendisse dignissim" />
  <Tag label="Dapibus elit" />
  <Tag label="Vel egestas felis" />
  <Tag label="Pharetra non" />
</Inline>

Columns

If you need to lay out content horizontally, Balance provides the Columns component:

<Columns gap="small">
  <Box background="muted" padding="small">
    <Text>Column 1</Text>
  </Box>
  <Box background="muted" padding="small">
    <Text>Column 2</Text>
  </Box>
  <Box background="muted" padding="small">
    <Text>Column 3</Text>
  </Box>
</Columns>

All columns are of equal width by default, but you can use the template prop to define proportional widths.

For example, if you wanted to render a main content area and a sidebar:

<Columns gap="small" template={[8, 4]}>
  <Box background="muted" padding="small">
    <Text>Main</Text>
  </Box>
  <Box background="muted" padding="small">
    <Text>Sidebar</Text>
  </Box>
</Columns>

Tone

The usage of colour in the system is designed to have a strong correlation with the tone of voice being used. The system makes available a spectrum of tones which are leveraged across the entire component suite.

Critical

Super important. You need to see this. Used for:

Caution

You should be aware something is happening or mid-way through a process. There could be a risk or an item that needs to be acted on. Used for:

Positive

Celebrate the successful outcome of an event or action. Used for:

Informative

Guidance & advice. Functional, calm and non urgent. Used for: