Skip to content
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.

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

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.
minWidthstring or objectThe minimum width of the box, growing if content is less than the minWidth. 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 greater 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.
minHeightstring or objectThe minimum height of the box, growing if content is less than the minHeight. 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 greater 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. Can be made responsive by passing an object of breakpoints. Can be any of the named color tokens.
colorstringThe text color of the Box. Can be made responsive by passing an object of breakpoints. Can be any of the named color tokens.
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.
gapnumber or objectSets the gaps between children elements . A size from our spacing scale. Can be made responsive by passing an object of breakpoints. Value(s) must be one of 1...10 values.
lineHeightstring or objectSets the line-height for the Box component. Must be valid line-height property values. Note: Copy component defines has it's own line-height
overflowstring or objectSets the overflow property . Must be valid overflow property values.
borderWidthstring or objectSets the border width for the Box component . Value(s) must be a valid css value with units.
borderStylestring or objectSets the border style for the Box component . Values must be one of none, hidden, dotted, dashed, solid, double, groove, inset, ridge, outset.
borderColorstring or objectSets the border color for the Box component. Can be any of the validColorValues
positionstring or objectSets the position property . Must be one of static, relative, absolute, fixed or sticky.
topstring or objectSpecifies the vertical position of a positioned element. It has no effect on non-positioned elements.
bottomstring or objectSpecifies the vertical position of a positioned element. It has no effect on non-positioned elements.
leftstring or objectSpecifies the horizontal position of a positioned element. It has no effect on non-positioned elements.
rightstring or objectSpecifies the horizontal position of a positioned element. It has no effect on non-positioned elements.
insetstring or objectShorthand that corresponds to the top, right, bottom, and/or left properties
isolatebooleanDetermines whether an element must create a new stacking context
zIndexnumber or objectSets the z-index property on Box component.
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 {colorDarkest, colorLightest} from '@nib-components/theme';
import {m, p} from '@nib/layout';
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>