Box

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/components-base

Package version

1.6.1

Loading...

<Box space={3}> <Typography>Hello world</Typography> </Box>

<Box space={3}>
  <Typography>Hello world</Typography>
</Box>

Introduction

import { Box } from '@telus-uds/components-base'

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 space={4}> <StackView direction={{ xs: 'column', md: 'row' }} space={4}> <Box flex={1} tokens={{ backgroundColor: '#fafafa' }} space={4}> <Typography>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} tokens={{ backgroundColor: '#fafafa' }} space={4}> <Typography>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 space={4}>
  <StackView direction={{ xs: 'column', md: 'row' }} space={4}>
    <Box flex={1} tokens={{ backgroundColor: '#fafafa' }} space={4}>
      <Typography>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} tokens={{ backgroundColor: '#fafafa' }} space={4}>
      <Typography>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 tokens={{ backgroundColor: '#eee' }} space={{ xs: 2, sm: 3, lg: 5, xl: 6 }}> <Typography>This box has wider padding on wider screens.</Typography> </Box>

<Box tokens={{ backgroundColor: '#eee' }} 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 tokens={{ backgroundColor: '#eee' }} 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 tokens={{ backgroundColor: '#eee' }} 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 tokens={{ backgroundColor: '#eee' }} 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 tokens={{ backgroundColor: '#eee' }} 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} tokens={{ backgroundColor: '#eee' }} 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} tokens={{ backgroundColor: '#eee' }} 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} tokens={{ backgroundColor: '#eee' }} 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} tokens={{ backgroundColor: '#eee' }} 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>"h2" tag on web</Typography> <Spacer space={2} /> <Typography>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>"h2" tag on web</Typography>
    <Spacer space={2} />
    <Typography>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

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
horizontal	union	space	Sets left and right padding using the theme's spacing scale. @see {@link SpacingValue}
vertical	union	space	Sets top and bottom padding using the theme's spacing scale. @see {@link SpacingValue}
top	union	vertical	Sets top padding using the theme's spacing scale. @see {@link SpacingValue}
bottom	union	vertical	Sets bottom padding using the theme's spacing scale. @see {@link SpacingValue}
left	union	horizontal	Sets left padding using the theme's spacing scale. @see {@link SpacingValue}
right	union	horizontal	Sets right padding using the theme's spacing scale. @see {@link SpacingValue}
variant	objectOf		System variant prop, see variants for more details
tokens	custom		System tokens prop, see tokens for more details
space	union		Sets default padding on all sides of the box using the theme's spacing scale. @see {@link SpacingValue}
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.
scroll	union		Renders a scrollable ScrollView instead of an unscrollable View. May take an object of ScrollView props which are passed to the rendered ScrollView.
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`).
children*	node		Box accepts any content as children.