📣
Have your say in our Mesh survey
Skip to content
Mesh
Stable

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·Playroom

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

Props

PropTypeDefaultDescription
padding, paddingVertical, paddingHorizontal, paddingTop, paddingRight, paddingBottom, paddingLeftnumber or objectA 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, marginLeftnumber or objectA size from our spacing scale. Can be made responsive by passing an object of breakpoints. Value(s) must be one of 1...10.
displaystring or objectHow 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.
widthstring or objectThe width of the box. Can be made responsive by passing an object of breakpoints. Value(s) must be a valid css value with units.
maxWidthstring or objectThe 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.
heightstring or objectThe height of the box. Can be made responsive by passing an object of breakpoints. Value(s) must be a valid css value with units.
maxHeightstring or objectThe 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.
justifyContentstring or objectWhen 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.
alignItemsstring or objectWhen 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.
flexDirectionstring or objectWhen 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.
flexWrapstring or objectWhen 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.
flexGrownumber or objectWhen 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.
flexShrinknumber or objectWhen 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.
textAlignstring or objectThe 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.
backgroundstringThe 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.
colorstringThe 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.
borderRadiusstringThe border radius of the Box. Must be one of none, small, standard, or full.
boxShadowstringThe box shadow of the Box. Must be one of none or standard.
childrennodeThe 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>

Related components