react-grid-flexbox

A couple of simple React components that implement CSS Grid and FlexBox to create powerful layouts.

Install

npm i --save react-grid-flexbox

Peer Dependencies

react prop-types styled-components

Motivation

The CSS Grid and FlexBox APIs are brilliant and can work beaufifully together to create just about any layout you can think of. The number of different API options can however make them a little tricky to work with and when you throw in things like different vendor prefixs, gutters and resposive design you've got something quite complicated in your hands.

This package aims to make it easier for developers to unlock the power of Grid and FlexBox by introducing two components (<Grid /> & <Flex />).

Both components offer a stripped down api for simplicity, while under the hood enforce a strict set of principals to ensure layouts are robust and it is difficult for them to be compramised by additional css.

Props

Quick note on Child Props Child Props (e.g _gridArea, _flexBasis & _flexGrow) can be applied to any child elemment of <Flex /> or <Grid /> regardless of the node type. See Example 1 below.

Quick note on Breakpoints Many of the props also support passing in a breakpoints object, giving you greater control over the layouts without having to touch any css. The pre configured breakpoints are: { tn: '0', xs: '500px', sm: '768px', md: '992px', lg: '1200px', xl: '1440px', hg: '1920px' } The props also support passing in any custom breakpoints object though for added convenience. - See Example 2 below.

Grid

Name	Type	Default	Description
Main Props
templateAreas (required)	String | ObjectOf(...breakpoints)		Used to define the 'named' template areas of the grid in which child elements can be placed. Uses same format as CSS grid-template-areas
templateColumns (optional)	String | ObjectOf(...breakpoints)	auto	Used to specify the template width of the grid columns. Uses same format as CSS grid-template-columns
templateRows (optional)	String | ObjectOf(...breakpoints)	auto	Used to specify the template height of the grid rows. Uses same format as CSS grid-template-rows
gutter (optional)	String | ObjectOf(...breakpoints)		Used to add the gutter between the child elements. Uses same format as CSS grid-gap
incGutterEdges (optional)	Boolean	false	Applies the gutter to the outer edges of the grid
className (optional)	String		If present, the grid will be wrapped in an extra div with the supplied className
children (optional)	ReactChildren		Grid content
----	----	-------	-----------
Child Props
_gridArea (required)	String | ObjectOf(...breakpoints)		Used to place the child in a grid area.

Flex

Name	Type	Default	Description
Main Props
direction (optional)	String | ObjectOf(...breakpoints)	column	Sets the flex-direction of child elements. Refer to CSS flex-direction for available options
wrap (optional)	Boolean	false	This option only works when direction="row" and will allow child elements to wrap to a new line
full (optional)	Boolean	false	This option only sets min-height and min-width to 100%
vAlign (optional)	String	top	Sets the vertical alignment of child elements (top, middle, bottom)
hAlign (optional)	String	left	Sets the horizontal alignment of child elements (left, center, right)
gutter (optional)	String | ObjectOf(...breakpoints)		Used to add the gutter between the child elements
incGutterEdges (optional)	Boolean	false	Applies the gutter to the outer edges of the flex box
className (optional)	String		If present, the grid will be wrapped in an extra div with the supplied className
children (optional)	ReactChildren		Flex content
----	----	-------	-----------
Child Props
_flexBasis (optional)	String | ObjectOf(...breakpoints)	auto	Sets the size of the child element using the CSS flex-basis prop and supports auto and [num]%/px/em/rem
_flexGrow (optional)	Boolean	false	Will cause child element to grow and fill remaining space (flex-grow)

Examples

1) Simple Grid

import React from 'react';
import { Grid, Flex } from 'react-grid-flexbox';
 
export default () => (
  <Grid
    templateRows="50px auto 100px"
    templateColumns="1fr 1fr 1fr"
    templateAreas={`
      "header header header"
      "sidebar main main"
      "footer footer footer"
    `}
    gutter="20px"
    incGutterEdges
  >
    <div _gridArea="header">...Header Content</div>
    <div _gridArea="sidebar">...SideBar Content</div>
    <div _gridArea="main">...Main Content</div>
    <div _gridArea="footer">...Footer Content</div>
  </Grid>
);

2) Advanced Responsive Grid

import React from 'react';
import { Grid, Flex } from 'react-grid-flexbox';
 
export default () => (
  <Grid
    templateRows={{
      tn: '50px 80px auto 100px',
      '600px': '80px 50px auto 100px',
      md: '50px auto 100px'
    }}
    templateColumns={{
      tn: '100%',
      md: '1fr 1fr 1fr'
    }}
    templateAreas={{
      tn: `
        "header"
        "sidebar"
        "main"
        "footer"
      `,
      '600px': `
        "sidebar"
        "header"
        "main"
        "footer"
      `,
      md: `
        "header header header"
        "sidebar main main"
        "footer footer footer"
      `,
    }}
    gutter={{
      tn: '10px',
      '600px': '10px 20px',
      md: '20px',
    }}
    incGutterEdges
  >
    <div _gridArea="header">...Header Content</div>
    <div _gridArea="sidebar">...SideBar Content</div>
    <div _gridArea="main">...Main Content</div>
    <div _gridArea="footer">...Footer Content</div>
  </Grid>
);

3) Simple Flex

import React from 'react';
import { Grid, Flex } from 'react-grid-flexbox';
 
export default () => (
  <Flex
    direction="row"
    gutter="20px"
    incGutterEdges
  >
    <div>1</div>
    <div>2</div>
    <div>3</div>
    <div>4</div>
  </Flex>
);

4) Combined Grid and Flex

import React from 'react';
import { Grid, Flex } from 'react-grid-flexbox';
 
export default () => (
  <Grid
    templateRows={{
      tn: '50px auto 100px',
      md: '50px auto 100px'
    }}
    templateColumns={{
      tn: '100%',
      md: '1fr 1fr 1fr'
    }}
    templateAreas={{
      tn: `
        "header"
        "main"
        "footer"
      `,
      md: `
        "header header header"
        "sidebar main main"
        "footer footer footer"
      `,
    }}
    gutter="20px"
    incGutterEdges
  >
    <Flex _gridArea="header" direction="row">
      <a _flexBasis="25%" href="#">Link One</a>
      <a _flexBasis="25%" href="#">Link Two</a>
      <a _flexBasis="25%" href="#">Link Three</a>
      <a _flexBasis="25%" href="#">Link Four</a>
    </Flex>
    <Flex _gridArea={{ tn: 'auto', md: 'sidebar' }}>
      <button>Button One</button>
      <button>Button Two</button>
      <button>Button Three</button>
      <button>Button Four</button>
    </Flex>
    <Flex _gridArea="main" direction="row" wrap>
      <Flex
        _flexBasis={{
          tn: '100%',
          md: '50%'
        }}
        gutter="20px"
      >
        <h1>Title One</h1>
        <p>Paragraph One</p>
      </Flex>
      <Flex
        _flexBasis={{
          tn: '100%',
          md: '50%'
        }}
        gutter="20px"
      >
        <h1>Title Two</h1>
        <p>Paragraph Two</p>
      </Flex>
    </Flex>
    <Flex _gridArea="footer">...Footer Content</Flex>
  </Grid>
);