Forma 36 - Grid

Grid is a CSS Grid based React component, comes with predefined values to ensure design consistency, and ease of use.

The Grid consists of two components:

Grid: Used as a container for grid items
Grid.Item: Elements within the Grid

Import

import { Grid } from '@contentful/f36-components';
// or
import { Grid } from '@contentful/f36-core';

Grid vs. Flexbox

The main difference between CSS Grid Layout and CSS Flexbox Layout is that flexbox was designed for layouts in one dimension - either a row or a column. Grid was designed for two-dimensional layout rows, and columns.

One dimensional columns without rows describing the use flexbox, and two dimensional grid describes how the grid works

Examples

Basic usage


function BasicGridExample() {
  return (
    <Grid columns="1fr 2fr" rowGap="spacingM" columnGap="spacingM">
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
    </Grid>
  );
}function BasicGridExample() {
  return (
    <Grid columns="1fr 2fr" rowGap="spacingM" columnGap="spacingM">
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray800, height: '100px' }} />
    </Grid>
  );
}

Repeat notation

repeat() is a css notation that you can use with the gridColumns and girdRows properties to make your rules more concise and easier to understand when creating a large amount of columns or rows

Example: gridColumns="1fr 2fr 1fr 2fr 1fr 2fr" is same as gridColumns="repeat(3, 1fr 2fr)" see below.


function RepeatNotationGridExample() {
  return (
    <>
      <Grid columns="1fr 2fr 1fr 2fr 1fr 2fr" columnGap="spacingM">
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
      </Grid>

      <Grid
        columns="repeat(3, 1fr 2fr)"
        columnGap="spacingM"
        marginTop="spacingM"
      >
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
      </Grid>
    </>
  );
}function RepeatNotationGridExample() {
  return (
    <>
      <Grid columns="1fr 2fr 1fr 2fr 1fr 2fr" columnGap="spacingM">
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray800, height: '100px' }}
        />
      </Grid>

      <Grid
        columns="repeat(3, 1fr 2fr)"
        columnGap="spacingM"
        marginTop="spacingM"
      >
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
        <Grid.Item
          style={{ backgroundColor: tokens.gray600, height: '100px' }}
        />
      </Grid>
    </>
  );
}

FR unit

Fr is a fractional unit and 1fr stands for 1 part of the available space. It differs from percentage unit because it distributes available space.

If you place a larger item into a track then the way the fr until will work is to allow that track to take up more space and distribute what is left over.


function FrGridExample() {
  const border = `1px solid ${tokens.gray700}`;
  return (
    <Grid columns="1fr 1fr 1fr">
      <p style={{ border }}>WelcomeToTheAwesomeContentfulGridSystem</p>
      <p style={{ border }}>Contentful</p>
      <p style={{ border }}>Forma 36</p>
      <p style={{ border }}>Welcome To The Awesome Contentful Grid System</p>
      <p style={{ border }}>Contentful</p>
      <p style={{ border }}>Forma 36</p>
    </Grid>
  );
}function FrGridExample() {
  const border = `1px solid ${tokens.gray700}`;
  return (
    <Grid columns="1fr 1fr 1fr">
      <p style={{ border }}>WelcomeToTheAwesomeContentfulGridSystem</p>
      <p style={{ border }}>Contentful</p>
      <p style={{ border }}>Forma 36</p>
      <p style={{ border }}>Welcome To The Awesome Contentful Grid System</p>
      <p style={{ border }}>Contentful</p>
      <p style={{ border }}>Forma 36</p>
    </Grid>
  );
}

Span keyword

Span keyword works on grid items with the gridArea property, use span to avoid specifying the end lines for a column or a row.

i.e. instead of specifying columnStart and columnEnd you can use span to make the grid item take 4 columns


function SpanKeywordGridExample() {
  return (
    <Grid columns={6}>
      <Grid.Item style={{ backgroundColor: tokens.gray700, height: '100px' }} />
      <Grid.Item
        area="span 4 / span 4"
        style={{ backgroundColor: tokens.gray700, height: '100px' }}
      />
    </Grid>
  );
}function SpanKeywordGridExample() {
  return (
    <Grid columns={6}>
      <Grid.Item style={{ backgroundColor: tokens.gray700, height: '100px' }} />
      <Grid.Item
        area="span 4 / span 4"
        style={{ backgroundColor: tokens.gray700, height: '100px' }}
      />
    </Grid>
  );
}

Content alignment

Just like Flex the Grid comes with justifyContent, justifyItems, alignItems, alignContent, ..etc.


function ContentAlignmentGridExample() {
  return (
    <Grid columns="250px 250px" justifyContent="space-between">
      <Grid.Item style={{ backgroundColor: tokens.gray700, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray700, height: '100px' }} />
    </Grid>
  );
}function ContentAlignmentGridExample() {
  return (
    <Grid columns="250px 250px" justifyContent="space-between">
      <Grid.Item style={{ backgroundColor: tokens.gray700, height: '100px' }} />
      <Grid.Item style={{ backgroundColor: tokens.gray700, height: '100px' }} />
    </Grid>
  );
}

Accessibility

According to WCAG C27 technique, the dom order must match the visual order.

The grid can re-order it's content in various ways through the order css property on grid items, this changes the visual order but the dom order stays the same, hence, keyboard navigation and focus order maybe affected.

Set the correct order of the elements with tabindex attribute to avoid accessibility issues.

Props (API reference)

Grid

Open in Storybook

Name
alignContent
Description
One of justify-content css values
"end"
"baseline"
"inherit"
"initial"
"start"
"center"
"-moz-initial"
"revert"
"unset"
string & {}
"space-around"
"space-between"
"space-evenly"
"stretch"
"flex-end"
"flex-start"
"normal"
Name
as
HTML Tag or React Component (e.g. div, span, etc)
Name
children
Description
Child nodes to be rendered in the component
ReactNode
Name
className
Description
CSS class to be appended to the root element
string
Name
columnGap
Description
One of Spacing tokens values, default is 0
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
columns
Description
Defines how many columns, default is `auto`
number
"none"
"auto"
"inherit"
"initial"
"-moz-initial"
"revert"
"unset"
"max-content"
"min-content"
string & {}
"subgrid"
Name
flow
Description
One of grid-auto-flow css values
"inherit"
"initial"
"-moz-initial"
"revert"
"unset"
string & {}
"column"
"dense"
"row"
Name
isInline
Description
Sets display:inline-grid
false
true
Name
justifyContent
Description
One of justify-content css values
"end"
"inherit"
"initial"
"start"
"left"
"center"
"right"
"-moz-initial"
"revert"
"unset"
string & {}
"space-around"
"space-between"
"space-evenly"
"stretch"
"flex-end"
"flex-start"
"normal"
Name
margin
Description
sets margin to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
marginBottom
Description
sets margin-bottom to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
marginLeft
Description
sets margin-left to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
marginRight
Description
sets margin-right to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
marginTop
Description
sets margin-top to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
padding
Description
sets padding to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
paddingBottom
Description
sets padding-bottom to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
paddingLeft
Description
sets padding-left to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
paddingRight
Description
sets padding-right to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
paddingTop
Description
sets padding-top to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
rowGap
Description
Spaces between rows, corresponds to of spacing tokens values, default is none
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
rows
Description
Defines how many rows, default is `auto`
number
"none"
"auto"
"inherit"
"initial"
"-moz-initial"
"revert"
"unset"
"max-content"
"min-content"
string & {}
"subgrid"
Name
testId
Description
A [data-test-id] attribute used for testing purposes
string

Grid.Item

Name
area
Description
one of grid-area css values
"auto"
"inherit"
"initial"
"-moz-initial"
"revert"
"unset"
string & {}
number & {}
Name
as
HTML Tag or React Component (e.g. div, span, etc)
Name
children
Description
Child nodes to be rendered in the component
ReactNode
Name
className
Description
CSS class to be appended to the root element
string
Name
columnEnd
Description
one of grid-column-end css values
"auto"
"inherit"
"initial"
"-moz-initial"
"revert"
"unset"
string & {}
number & {}
Name
columnStart
Description
one of grid-column-start css values
"auto"
"inherit"
"initial"
"-moz-initial"
"revert"
"unset"
string & {}
number & {}
Name
margin
Description
sets margin to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
marginBottom
Description
sets margin-bottom to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
marginLeft
Description
sets margin-left to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
marginRight
Description
sets margin-right to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
marginTop
Description
sets margin-top to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
order
Description
order css property
number
Name
padding
Description
sets padding to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
paddingBottom
Description
sets padding-bottom to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
paddingLeft
Description
sets padding-left to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
paddingRight
Description
sets padding-right to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
paddingTop
Description
sets padding-top to one of the corresponding spacing tokens
"none"
"spacing2Xs"
"spacingXs"
"spacingS"
"spacingM"
"spacingL"
"spacingXl"
"spacing2Xl"
"spacing3Xl"
"spacing4Xl"
Name
rowEnd
Description
one of grid-row-end css values
"auto"
"inherit"
"initial"
"-moz-initial"
"revert"
"unset"
string & {}
number & {}
Name
rowStart
Description
one of grid-column-start css values
"auto"
"inherit"
"initial"
"-moz-initial"
"revert"
"unset"
string & {}
number & {}
Name
testId
Description
A [data-test-id] attribute used for testing purposes
string

Import

Grid vs. Flexbox

Examples

Basic usage

Repeat notation

FR unit

Span keyword

Content alignment

Accessibility

Props (API reference)

Grid

alignContent

as

children

className

columnGap

columns

flow

isInline

justifyContent

margin

marginBottom

marginLeft

marginRight

marginTop

padding

paddingBottom

paddingLeft

paddingRight

paddingTop

rowGap

rows

testId

Grid.Item

area

as

children

className

columnEnd

columnStart