Box

v3.0.5 Edit this page

<Box> and <BoxContainer> are simple atomic layout components with a declarative React API that support the NDS Grid Guidelines.

Used to

  1. Codify standardized component and page level layouts at NerdWallet.
  2. Bridge the gap between Design and Eng.
  3. Obviate need for much of the custom media query logic previously required.

See the NDS Grid Guidelines for a more comprehensive picture on the rationale behind Box at NerdWallet, as well as descriptions of the difference between adaptive and fluid layouts, etc.

Usage

Loading examples...

Props

<BoxContainer>

Simple convenience wrapper that defines the content area from the grid guidelines of the design system. Provides outer margin and max width by default. Used to stop fluidity of columns beyond the max-content-width specified in base-styles. padding-horizontal-3 and padding-horizontal-5--wide that are unique to BoxContainer and should take precedence over the default Box styling.

Name

Description

Type

Default

children

node

<Box>

Atomic alignment component. Internally knows about the NDS breakpoint. Used to implement component and page level layout around a consistent grid system.

Name

Description

Type

Default

children

node

null

className

string

null

component

React component or HTML element to use instead of div.

custom

'div'

isReactNative

Boolean flag to indicate if a stylesheet should be created for React Native.

bool

false

notWide

Object to indicate the behavior of the flex container in the narrower (>=768) breakpoint.

shape of:

{ columns: 'auto', direction: 'row', display: 'flex', noGutter: null, justify: 'flex-start', wrap: 'wrap', }

notWide.noGutter

Remove the horizontal padding around the left, right, or both sides of Box. Intended to be used on the outer columns of the Grid (reason for the name of the prop).

one of [[object Object],[object Object],[object Object]]

notWide.direction

Align items (symmetric to flexbox) along the cross-axis.

string

notWide.justify

Arrange the boxes based on cross and main axis within the narrower breakpoint. Behaves like the justify-content CSS property and supports the standard.

one of [[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]]

notWide.columns

Number to indicate how many columns to fill the flex container in the smaller (<= 767) breakpoint. If this is set with a prop other than the default, we apply display-flex.

one of [[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]]

notWide.wrap

Flag to indicate if flexbox items should wrap or nowrap. Default is wrap.

one of [[object Object],[object Object]]

wide

Object to indicate the behavior of the the flex container in the wider (>=768) breakpoint.

shape of:

{ columns: 'auto', direction: 'row', display: 'flex', noGutter: null, justify: 'flex-start', wrap: 'wrap', }

wide.noGutter

Remove the horizontal padding around the left, right, or both sides of Box. Intended to be used on the outer columns of the Grid (reason for the name of the prop).

one of [[object Object],[object Object],[object Object]]

wide.direction

Align items (symmetric to flexbox) along the cross-axis.

string

wide.justify

Arrange the boxes based on cross and main axis within the narrower breakpoint. Behaves like the justify-content CSS property and supports the standard.

one of [[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]]

wide.columns

Number to indicate how many columns to fill the flex container in the wider (>= 768) breakpoint. If this is set with a prop other than the default, we apply display-flex.

one of [[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]]

wide.wrap

Flag to indicate if flexbox items should wrap or nowrap. Default is wrap.

one of [[object Object],[object Object]]

Within <BoxContainer>

<Box> is normally used within the context of a <BoxContainer>, which applies a constrained max-width and outer side margins, specified by the NDS Grid Guidelines:

This should generally be the use case for adopting Box in your flow.

As a replacement for <ContentContainer />

<BoxContainer> should be a drop in replacement for the older <ContentContainer /> component. Just compose children as you would've previously:

Known Consumers

The following repos have adopted @nerdwallet/react-box to implement some of their layouts:

<Box> Design

Read more about the design of Box?

Box Design

<Box> is an atomic layout component. Along with breakpoints, and guidelines, it's one of the building blocks of the NDS grid system. This doc covers some of the original high level rationale around the implementation and design.

For more info on layout guidelines in general, see the NDS Grid Guidelines.

Features and Functionality

  • Designed for future-forward layouts
  • Internal media queries mapping to @breakpoint-wide from base-styles
  • Declarative, React API to offer familiar ergonomics
  • Maintained symmetry with pre-existing flexbox APIs to minimize overhead, confusion of learning a new syntax and ease adoption

API

Iterations

We iterated (and are still iterating) on various different APIs for <Box>. Here are some older iterations:

See the README.md and the Storybook examples for the current iteration.

Adoption

Right now there are numerous breakpoints all through the product; it will take some time for teams to converge on a single breakpoint. As such <Box> will most likely be a gradual adoption as teams gain resources and prioritization to build their layouts in line with the new grid system.

Maintainers

This component was created by Piper Chester.