Box

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/ds-allium

Package version

1.14.0

Loading...

<Box variant={{ background: 'light' }} space={3}> <Typography>Hello world</Typography> </Box>

<Box variant={{ background: 'light' }} space={3}>
  <Typography>Hello world</Typography>
</Box>

Introduction

import { Box } from '@telus-uds/ds-allium'

Box creates space (padding) around content, and has variants that give content a background.

Guidance

Use Box to create padding within a container, around all its content. To create space after a box, between boxes or between items in a box, combine Box with other layout components, such as StackView and Spacer:

Loading...

<Box variant={{ background: 'light' }} space={4}> <StackView direction={{ xs: 'column', md: 'row' }} space={4}> <Box flex={1} variant={{ background: 'lightest' }} space={4}> <Typography variant={{ size: 'h3' }}>Some content</Typography> <Spacer space={4} /> <Typography>Some example content within the first box.</Typography> <Spacer space={2} /> <Typography>Another line of text in the first box.</Typography> </Box> <Box flex={1} variant={{ background: 'lightest' }} space={4}> <Typography variant={{ size: 'h3' }}>More content</Typography> <Spacer space={4} /> <Typography>Some example content within the second box.</Typography> <Spacer space={2} /> <Typography>Another line of text in the second box.</Typography> </Box> </StackView> </Box>

<Box variant={{ background: 'light' }} space={4}>
  <StackView direction={{ xs: 'column', md: 'row' }} space={4}>
    <Box flex={1} variant={{ background: 'lightest' }} space={4}>
      <Typography variant={{ size: 'h3' }}>Some content</Typography>
      <Spacer space={4} />
      <Typography>Some example content within the first box.</Typography>
      <Spacer space={2} />
      <Typography>Another line of text in the first box.</Typography>
    </Box>
    <Box flex={1} variant={{ background: 'lightest' }} space={4}>
      <Typography variant={{ size: 'h3' }}>More content</Typography>
      <Spacer space={4} />
      <Typography>Some example content within the second box.</Typography>
      <Spacer space={2} />
      <Typography>Another line of text in the second box.</Typography>
    </Box>
  </StackView>
</Box>

space prop

The space prop sets the default padding on all sides, using the spacing scale.

Simple numbers may be used, or objects (see spacing scale docs for details. These examples change spacing depending on the viewport.

Loading...

<Box variant={{ background: 'light' }} space={{ xs: 2, sm: 3, lg: 5, xl: 6 }}> <Typography>This box has wider padding on wider screens.</Typography> </Box>

<Box variant={{ background: 'light' }} space={{ xs: 2, sm: 3, lg: 5, xl: 6 }}>
  <Typography>This box has wider padding on wider screens.</Typography>
</Box>

horizontal and vertical props

These props are the same as the space prop but apply space specifically on the left and right (horizontal) or top and bottom (vertical) sides of a box. If space and horizontal or vertical are provided, space is treated as the default and the more specific props as overrides.

Loading...

<Box variant={{ background: 'light' }} vertical={4} horizontal={{ xs: 2, sm: 3, lg: 5, xl: 6 }}> <Typography> This box has wider horizontal padding on wider screens, and stable vertical padding. </Typography> </Box>

<Box variant={{ background: 'light' }} vertical={4} horizontal={{ xs: 2, sm: 3, lg: 5, xl: 6 }}>
  <Typography>
    This box has wider horizontal padding on wider screens, and stable vertical padding.
  </Typography>
</Box>

left, right, top and bottom props

These props are the same as the space props above but apply to one specific side only. If one of these is provided alongside space, horizontal or vertical, those are treated as the defaults and the more specific prop as an override.

Loading...

<Box variant={{ background: 'light' }} space={4} bottom={{ xs: 2, sm: 3, lg: 5, xl: 6 }}> <Typography> This box has wider bottom padding on wider screens, and stable padding on other sides. </Typography> </Box>

<Box variant={{ background: 'light' }} space={4} bottom={{ xs: 2, sm: 3, lg: 5, xl: 6 }}>
  <Typography>
    This box has wider bottom padding on wider screens, and stable padding on other sides.
  </Typography>
</Box>

flex prop and layout

By default, the box takes its minimum width as the width of its children (flex value of 0). flex={1} may be passed to make the box stretch and grow to fit a flex container.

Other values greater than 0 may be passed to distribute space proportionately. See the React Native flex documentation for more details. Behaviour is similar on web and in native apps.

Loading...

<StackView direction="row" space={3}> <Box space={3} variant={{ background: 'light' }} flex={1}> <Typography> This box has flex prop set to 1. It grows and shrinks, claiming half as much space as its flex: 2 neighbour. </Typography> </Box> <Box space={3} variant={{ background: 'light' }} flex={2}> <Typography> This box has flex prop set to 2. It grows and shrinks, claiming twice as much space as its flex: 1 neighbour. </Typography> </Box> </StackView>

<StackView direction="row" space={3}>
  <Box space={3} variant={{ background: 'light' }} flex={1}>
    <Typography>
      This box has flex prop set to 1. It grows and shrinks, claiming half as much space as its
      flex: 2 neighbour.
    </Typography>
  </Box>
  <Box space={3} variant={{ background: 'light' }} flex={2}>
    <Typography>
      This box has flex prop set to 2. It grows and shrinks, claiming twice as much space as its
      flex: 1 neighbour.
    </Typography>
  </Box>
</StackView>

Accessibility

By default, Box applies no accessibility props or values relevant to accessibility tools. It may accept React Native accessibility props (web docs, native docs), and applies them to the outer container.

Tag prop for semantic HTML

By default, Box renders a <div> on web and a View with no accessibility role on native apps.

To render a HTML attribute with a semantic meaning on web, pass a string naming a HTML semantic layout tag to the tag prop. An accessibilityRole may also be passed if a role is needed in native apps. Heading tags (h1, h2, h3, h4, h5, h6) are by default mapped to "heading" role in native apps.

See the tag entry in the props table for the full list of supported tags.

Loading...

<Box tag="main"> <Box tag="h2" space={2}> <Typography variant={{ size: 'h1' }}>"h2" tag on web</Typography> <Spacer space={2} /> <Typography variant={{ size: 'h4' }}> This subheading is part of the semantic h2 heading </Typography> </Box> <Box tag="article" space={2}> <Typography>This is inside an "Article" tag on web.</Typography> <Typography>In native apps, it is treated like any other content.</Typography> <Typography>The h2 above it is treated as accessibilityRole="heading".</Typography> </Box> <Box tag="label" space={2} nativeID="label-box" accessibilityRole="header"> <Typography>All text in this box is treated as a "Label" on web.</Typography> <Typography>In native apps, it is set to behave as a "header".</Typography> </Box> <Box tag="section" space={2} accessibilityLabelledBy="label-box"> <Typography>This is inside a "Section" tag on web.</Typography> <Typography>On web, the label box's content is this section box's accessible name.</Typography> <Typography>This helps users of accessibility tools understand a page's structure.</Typography> <Typography> In native apps, headers may be the closest equivalent to named sections. </Typography> </Box> </Box>

<Box tag="main">
  <Box tag="h2" space={2}>
    <Typography variant={{ size: 'h1' }}>"h2" tag on web</Typography>
    <Spacer space={2} />
    <Typography variant={{ size: 'h4' }}>
      This subheading is part of the semantic h2 heading
    </Typography>
  </Box>
  <Box tag="article" space={2}>
    <Typography>This is inside an "Article" tag on web.</Typography>
    <Typography>In native apps, it is treated like any other content.</Typography>
    <Typography>The h2 above it is treated as accessibilityRole="heading".</Typography>
  </Box>
  <Box tag="label" space={2} nativeID="label-box" accessibilityRole="header">
    <Typography>All text in this box is treated as a "Label" on web.</Typography>
    <Typography>In native apps, it is set to behave as a "header".</Typography>
  </Box>
  <Box tag="section" space={2} accessibilityLabelledBy="label-box">
    <Typography>This is inside a "Section" tag on web.</Typography>
    <Typography>On web, the label box's content is this section box's accessible name.</Typography>
    <Typography>This helps users of accessibility tools understand a page's structure.</Typography>
    <Typography>
      In native apps, headers may be the closest equivalent to named sections.
    </Typography>
  </Box>
</Box>

Platform considerations

The component is available on both native platforms and web.

Scrollable boxes

The prop scroll may be used to make a box scrollable. This changes the box from rendering a View to rendering a ScrollView. If an object is passed to the scroll prop, its properties are passed to the ScrollView as props.

On native apps, where screens do not scroll by default, a Box with scroll set and appropriate spacing and background colour is therefore a good first container for an app screen.

Do not use scroll to make a box within a page scrollable, unless it is as part of a component with a design that is accessible and makes it visually apparent that additional content can be reached. See Tabs for an example of such a component.

Props

Name	Type	Default	Description
bottom	spacingIndexPropType | spacingObjectPropType	vertical	Sets bottom padding using the theme's spacing scale. @see {@link SpacingValue}
children*	node		Box accepts any content as children.
flex	number		Sets the 'flex' style, which controls 'flexGrow', 'flexShrink' and 'flexBasis' styles. Set as 1 for the box to stretch and grow to fit in the available space, or another number to share space disproportionately with siblings. See https://reactnative.dev/docs/flexbox#flex for details. With the default '0', the box takes its minimum width from its content.
horizontal	spacingIndexPropType | spacingObjectPropType	space	Sets left and right padding using the theme's spacing scale. @see {@link SpacingValue}
left	spacingIndexPropType | spacingObjectPropType	horizontal	Sets left padding using the theme's spacing scale. @see {@link SpacingValue}
right	spacingIndexPropType | spacingObjectPropType	horizontal	Sets right padding using the theme's spacing scale. @see {@link SpacingValue}
scroll	bool | ScrollView.propTypes ? PropTypes.shape(ScrollView.propTypes) : PropTypes.object		Renders a scrollable ScrollView instead of an unscrollable View. May take an object of ScrollView props which are passed to the rendered ScrollView.
space	spacingIndexPropType | spacingObjectPropType		Sets default padding on all sides of the box using the theme's spacing scale. @see {@link SpacingValue}
tag	'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'article' | 'aside' | 'blockquote' | 'footer' | 'figure' | 'form' | 'header' | 'ul' | 'li' | 'main' | 'nav' | 'section' | 'label'		Optional semantic HTML tag, to apply to the container on web. Does not change styling. In native apps, if a header tag is provided ("h1", "h2" etc) and accessibilityRole prop is not defined, the accessibilityRole will default to "heading".
testID	string		Use in tests if the box itself needs to be targetted and no other way of selecting the box is available (e.g. it cannot be targetted using an appropriate 'accessibilityRole').
tokens	custom		System tokens prop, see tokens for more details
top	spacingIndexPropType | spacingObjectPropType	vertical	Sets top padding using the theme's spacing scale. @see {@link SpacingValue}
variant	objectOf		System variant prop, see variants for more details
vertical	spacingIndexPropType | spacingObjectPropType	space	Sets top and bottom padding using the theme's spacing scale. @see {@link SpacingValue}

Tokens

In exceptional circumstances, the following tokens can be passed to this component to override its default styles. Do not do this unless absolutely necessary. Read more about overriding styles.

View Tokens

Prop Name	Token Property	Token Type
tokens	backgroundColor	color

Figma

Variants

Background

Controls the background colour of the box. If not set, the box's background is transparent.

{ background: 'lightest' }

A pure white background.

Loading...

<Box variant={{ background: 'lightest' }} space={4}> <Typography>background: 'lightest'</Typography> </Box>

<Box variant={{ background: 'lightest' }} space={4}>
  <Typography>background: 'lightest'</Typography>
</Box>

{ background: 'light' }

A subtle grey background.

Loading...

<Box variant={{ background: 'light' }} space={4}> <Typography>background: 'light'</Typography> </Box>

<Box variant={{ background: 'light' }} space={4}>
  <Typography>background: 'light'</Typography>
</Box>

{ background: 'dark' }

A heavy grey background. Content within this box should use the inverse variant where it is available.

Loading...

<Box variant={{ background: 'dark' }} space={4}> <Typography variant={{ inverse: true }}>background: 'dark'</Typography> </Box>

<Box variant={{ background: 'dark' }} space={4}>
  <Typography variant={{ inverse: true }}>background: 'dark'</Typography>
</Box>

{ background: 'darkest' }

A very dark grey background. Content within this box should use the inverse variant where it is available.

Loading...

<Box variant={{ background: 'darkest' }} space={4}> <Typography variant={{ inverse: true }}>background: 'dark'</Typography> </Box>

<Box variant={{ background: 'darkest' }} space={4}>
  <Typography variant={{ inverse: true }}>background: 'dark'</Typography>
</Box>

{ background: 'critical' }

A dark red background. Use to alert users to a problem that requires immediate attention. Content within this box should use the inverse variant where it is available.

Loading...

<Box variant={{ background: 'critical' }} space={4}> <Typography variant={{ inverse: true }}>background: 'critical'</Typography> </Box>

<Box variant={{ background: 'critical' }} space={4}>
  <Typography variant={{ inverse: true }}>background: 'critical'</Typography>
</Box>

{ background: 'danger' }

A pink / soft red background. Use carefully to alert users of a problem or warn that an action may have a cost such as costing money or losing data. Content within this box should use danger variants where they are available.

Loading...

<Box variant={{ background: 'danger' }} space={4}> <Button variant={{ danger: true }} onPress={() => {}}> background: 'danger' </Button> </Box>

<Box variant={{ background: 'danger' }} space={4}>
  <Button variant={{ danger: true }} onPress={() => {}}>
    background: 'danger'
  </Button>
</Box>

{ background: 'warning' }

A yellow background. Use carefully to alert users to something requiring careful attention.

Loading...

<Box variant={{ background: 'warning' }} space={4}> <Typography variant={{ bold: true }}>background: 'warning'</Typography> </Box>

<Box variant={{ background: 'warning' }} space={4}>
  <Typography variant={{ bold: true }}>background: 'warning'</Typography>
</Box>

{ background: 'positive' }

A green background. Use when notifying users of a positive event, such as an action having completed successfully.

Loading...

<Box variant={{ background: 'positive' }} space={4}> <Typography variant={{ bold: true }}>background: 'positive'</Typography> </Box>

<Box variant={{ background: 'positive' }} space={4}>
  <Typography variant={{ bold: true }}>background: 'positive'</Typography>
</Box>

{ background: 'brand' }

A purple background. Use sparingly as part of approved on-brand designs that create a bold visual impression. Content within this box should use the inverse variant where it is available.

Loading...

<Box variant={{ background: 'brand' }} space={4}> <Typography variant={{ inverse: true }}>background: 'brand'</Typography> </Box>

<Box variant={{ background: 'brand' }} space={4}>
  <Typography variant={{ inverse: true }}>background: 'brand'</Typography>
</Box>

Feedback

• Spotted a problem with this component? Raise an issue on GitHub
• See any existing issues for this component
• Contact the team on slack in #ds-allium-support