1.6.0

Box

Box is an extremely powerful component. It is a low-level primitive component that accepts props for standard spacing, background and text colors, display properties and more. It will negate the need to create many custom styled components in your applications.

GitHub·Storybook

Installation

bash

npm install @nib/layout

Usage

jsx

import {Box} from '@nib/layout';

Do not style layout components

You must not apply styled-components to this component as it will interfere with the structure required for the current styling. This is true for all layout components.

Interactive demo

Lorem ipsum dolor sit amet.

jsx

<Box padding={4} background="lightest" color="black" borderRadius="standard">
  <Copy>Lorem ipsum dolor sit amet.</Copy>
</Box>

<Box padding={4} background="lightest" color="black" borderRadius="standard">
  <Copy>Lorem ipsum dolor sit amet.</Copy>
</Box>

Props

Prop	Type	Description
`padding`, `paddingVertical`, `paddingHorizontal`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`	number or object	A size from our spacing scale. Can be made responsive by passing an object of breakpoints. Value(s) must be one of `1...10`.
`margin`, `marginVertical`, `marginHorizontal`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft`	number or object	A size from our spacing scale. Can be made responsive by passing an object of breakpoints. Value(s) must be one of `1...10`.
`display`	string or object	How the box should display. Can be made responsive by passing an object of breakpoints. Value(s) must be one of `none`, `inline`, `block`, `inline-block`, `flex`, `inline-flex`.
`width`	string or object	The width of the box. Can be made responsive by passing an object of breakpoints. Value(s) must be a valid css value with units.
`maxWidth`	string or object	The maximum width of the box, shrinking if content is less than the maxWidth. Can be made responsive by passing an object of breakpoints. Value(s) must be a valid css value with units.
`height`	string or object	The height of the box. Can be made responsive by passing an object of breakpoints. Value(s) must be a valid css value with units.
`maxHeight`	string or object	The maximum height of the box, shrinking if content is less than the maxHeight. Can be made responsive by passing an object of breakpoints. Value(s) must be a valid css value with units.
`justifyContent`	string or object	When display is set to `flex/inline-flex` this aligns the Box children along the cross axis (horizontal by default). Can be made responsive by passing an object of breakpoints. Value(s) must be one of `center`, `flex-start`, `flex-end`, `space-between`, or `space-around`.
`alignItems`	string or object	When display is set to `flex/inline-flex` this aligns the Box children along the main axis (vertical by default). Can be made responsive by passing an object of breakpoints. Value(s) must be one of `flex-start`, `center`, or `flex-end`.
`flexDirection`	string or object	When display is set to `flex/inline-flex` this sets the main axis and direction of the Box. Can be made responsive by passing an object of breakpoints. Value(s) must be one of `row`, `column`, `row-reverse`, or `column-reverse`.
`flexWrap`	string or object	When display is set to `flex/inline-flex` this sets whether flex items are forced onto one line or can wrap onto multiple lines. Can be made responsive by passing an object of breakpoints. Value(s) must be one of `wrap` or `nowrap`.
`flexGrow`	number or object	When Box is a flex-item this sets whether the Box should grow to fill remaining space. Can be made responsive by passing an object of breakpoints. Value(s) must be a number.
`flexShrink`	number or object	When Box is a flex-item this sets whether the Box should shrink to fit within available space. Can be made responsive by passing an object of breakpoints. Value(s) must be a number.
`textAlign`	string or object	The text alignment of the Box. Can be made responsive by passing an object of breakpoints. Value(s) must be one of `left`, `center`, or `right`.
`background`	string	The background color of the Box. Must be one of `brandBase`, `brandLight`, `brandDark`, `accent`, `black`, `darkest`, `darker`, `dark`, `light`, `lighter`, `lightest`, `white`, `hospital`, `extras`, `combined`, `highlightBg`, or `highlightText`.
`color`	string	The text color of the Box. Must be one of `brandBase`, `brandLight`, `brandDark`, `accent`, `black`, `darkest`, `darker`, `dark`, `light`, `lighter`, `lightest`, `white`, `hospital`, `extras`, `combined`, `highlightBg`, or `highlightText`.
`borderRadius`	string	The border radius of the Box. Must be `standard` if set.
`children`	node	The contents of the Box.

Considerations

The Box component can be used in place of a div whenever padding, background color, text color, border radius, text alignment or basic flex styling needs to be applied to a component.

Prior to this Box component, you would have had to have done something like this to add common, standard styling to a component:

jsx

import styled from 'styled-components';
import {m, p} from 'styled-components-spacing';
import {colorDarkest, colorLightest} from '@nib-components/theme';
const MyBox = styled.div`
  ${m(5)};
  ${p({xs: 4, md: 6})};
  background-color: ${colorDarkest};
  border-radius: 4px;
  color: ${colorLightest};
  text-align: center;
`;

Now with Box you do not need to step out of the component you are working on to import a bunch of boilerplate and define a styled component that meets your specific needs. Just use the props provided by Box:

jsx

<Box margin={5} padding={{xs: 4, md: 6}} background="darkest" color="lightest" borderRadius="standard" textAlign="center">
  Hello world
</Box>

DOM element

The Box component is a styled div element. To change this you can use the styled components as prop:

jsx

<Box padding={4} as="aside">
  <Stack space={4}>
    <Heading size={4}>Newsletter</Heading>
    <Copy>Lorem ipsum dolor sit amet.</Copy>
    <Link href="/subsribe">Sign up now</Link>
  </Stack>
</Box>

Stack

Edit this page

Box