README

react-grid-area

Filter grid areas according to the css grid-template property.

Background

CSS Grids support templates where each region of the grid can be named. Only named areas within the grid are visible and the layout is defined by the css property. This is extremely powerful, especially for responsive layouts where you might want to change the layout per device or even swap out components for different screen sizes. The only problem with this is that all areas will be rendered, even when not visible with the current template. This might result in your application doing more work than necessary.

react-grid-area attempts to solve this, by only rendering areas explicitly listed in the grid-template css property.

If you are not already familiar with css grids, then it is highly recommended to read https://css-tricks.com/snippets/css/complete-guide-grid/ or https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout

Install

yarn add react-grid-area

npm install react-grid-area

Constraints

Grid components must be named (in most cases React will take care of this for you). The component name will be used as the css grid area name.

Example Usage

The following TypeScript example shows how react-grid-area could be used as a top level page layout tool.

import React from 'react'
import { Grid, layout } from 'react-grid-area'

import Header from '../Header'
import Footer from '../Footer'
import Menu from '../Menu'
import Faq from '../Faq'
import Home from '../Home'

// arrange the components using the css grid-template property format
// for more info: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template
const layouts = {
  home_desktop: layout`
    "${Header} ${Header}" auto
    "${Menu}   ${Home}"   1fr
    "${Footer} ${Footer}" auto / auto 1fr`,
  home_mobile: layout`
    "${Header}" auto
    "${Home}"   1fr
    "${Footer}" auto`,
  faq_desktop: layout`
    "${Header} ${Header}" auto
    "${Menu}   ${Faq}"   1fr
    "${Footer} ${Footer}" auto / auto 1fr`,
  faq_mobile: layout`
    "${Header}" auto
    "${Faq}"    1fr
    "${Footer}" auto`
}

const App: React.FunctionComponent<{ page: string; screenSize: string }> = ({ page, screenSize }) => (
  <Grid
    layout={layouts[`${page}_${screenSize}`]}
    /* optional props will be forwarded to each component in the layout */
    props={{ some: 'props' }}
  />
)

Tag and Styling

By default react-grid-area will output a div tag for the grid container, you can change this by passing a tag name.

For custom styling, react-grid-area supports the className property.

import { Grid, layout } from 'react-grid-area'
import styled from 'styled-components'
import Page from '../Page'

const StyledGrid = styled(Grid)`
  flex-grow: 1;
  grid-gap: 1em;
`

const pageLayout = layout`"${Page}"`

export default ({ page, screenSize }) => <StyledGrid tag="main" layout={pageLayout} />

Dynamic values

Layout values can be dynamically generated, so long as dynamic values return either a string or number.

const largeHeader = true
const bodyWidth = '1fr'
const bodyHeight = '1fr'

const layouts = {
  home_desktop: layout`
    "${Header} ${Header}" ${largeHeader ? 6 : 4}em
    "${Menu}   ${Home}"   ${bodyHeight}
    "${Footer} ${Footer}" auto / auto ${bodyWidth}`
}

Usage no npm install needed!