Skip to content

Grid

Grid is used to build layouts using CSS Grid without writing custom CSS.

  • Use Grid when you want to arrange elements along the horizontal and vertical planes
    • Grid is particularly powerful when you need rows or columns of a consistent size
  • Consider Flex when you want to arrange elements in one direction
    • Flex is great for vertical centering or spacing two elements on opposite ends of a container
  • It’s best to learn the basic spec before learning how it is applied through the Grid component
  • Grid implements Box and accepts all the same properties
  • As with Box, numerical spacing values passed to Grid and GridItem will be interpreted as increments of our spacing unit
  • Shorthand properties like grid, gap, place-items, and place-content are not currently supported
  • Grid layouts are frequently built using fr units
  • GridItem is a re-export of Box and equivalent in every way; it exists to help differentiate conceptually between a grid item and its contents
    • Using inline elements as grid items (e.g. buttons, icons, tags) can lead to unexpected behavior; GridItem is intended to act as a wrapper around this content, though any block-level element—including Box—can serve the same purpose

Jump to: Columns | Rows | Alignment | Responsive grids | Advanced techniques

Use the templateColumns prop to define grid columns.Use columnGap to add spacing between columns.The repeat functions allows you to concisely define columns of the same measurement.

templateColumns="repeat(3, 1fr)" is equivalent to templateColumns="1fr 1fr 1fr"—or “three columns that take up an equal share of available space”.

Hard-coding column counts is not very flexible with dynamic layouts.

auto-fit allows you to automatically fill the space with as many columns as will fit.minmax allows you to specify a minimum and maximum width of a column.

The example below instructs the browser to fill the space with columns with a minimum width of 100px and maximum width of 1fr.

Alternatively, autoColumns allows us to specify the width of any “implicit” columns. All columns in the example below are implicit because we haven’t explicitly defined any columns using the templateColumns property.

Columns of 50px (as defined by autoColumns) are being added as a result of being placed by the columnStart and columnEnd properties.

Implicit layouts can become confusing—especially in the context of columns.The related prop autoRows is more practical.

The columnStart and columnEnd properties can be used to specify a grid item’s start/end position within grid columns. Grid column locations begin at position 1 on the far left of the grid.The span directive can be used in place of explicitly specifying start/end points.

Use the templateRows prop to define grid rows. Use rowGap to add spacing between rows.

The rowStart and rowEnd properties can be used to specify a grid item’s start/end position within grid rows. Grid row locations begin at position 1 at the very top of the grid.The span directive can be used in place of explicitly specifying start/end points.

Alternatively, autoRows allows us to specify the height of any “implicit” rows. In the example below, we define two explicit rows at 100px and any implicit rows will be 50px high. Row height will be determined by the size of its content in the absence of an autoRows value.

Justify vs align? Items vs content vs self? It’s all very confusing and the effect of these properties depends on the layout mode being used.

Common terms when working with CSS grid alignment
TermDefinition
justifyDefine alignment along the inline (row/horizontal) axis
alignDefine alignment along the block (column/vertical) axis
itemsThe direct children of a parent on which the grid is defined
contentThe content inside of the items; typically only relevant when the content is smaller than the item
selfUsed to specify alignment or justification of a single element (as opposed to most other rules, which apply to all children)

We can place grid items along the inline (row/horizontal) axis using justifyItems. Defaults to stretch.

This is more common when creating larger, structural layouts.

We can place grid items along the block (column/vertical) axis using alignItems. Defaults to stretch.

This is more common when creating larger, structural layouts.

Use justifyContent to place the items along the inline (row/horizontal) axis if the contents of the grid are narrower than the width of the grid container.

This is common when the grid items are smaller UI elements, such as buttons, links, or icons.

Use alignContent to place the items along the block (column/vertical) axis if the contents of the grid are shorter than the height of the grid container.

This is common when the grid items are smaller UI elements, such as buttons, links, or icons.

We can place an individual grid item along the inline (row/horizontal) axis using justifySelf. Defaults to stretch.Use justifyItems if you want to set the value on all items.

We can place an individual grid item along the block (column/vertical) axis using alignSelf. Defaults to stretch.Use alignItems if you want to set the value on all items.

The example below demonstrates four rows at 100px, each aligned differently.

Most layouts will need to be adapted based on the size of the viewport. Box—on top of which Grid is built—provides a mechanism for specifying the value of “responsive properties” at our different breakpoint values.

The example below demonstrates how we can alter templateColumns at our different breakpoint values.

“Responsive properties” rely on WorkbenchProvider, which measures document.body to determine the breakpoint value. Resizing the example below won’t trigger the breakpoint change, but resizing the browser itself will.

autoFlow controls the placement of “implicit cells/tracks”. By default, items will be placed to fill each row consecutively, adding new rows as necessary.

Referring to grid areas by name can be a powerfully declarative tool. Here is an example of this in use with the “Holy Grail” layout.

While it is possible to specify templateAreas using the Grid component, the unique syntax for this property makes it a bit difficult to work with. It may be easier to write custom CSS if you plan to use this property extensively.

Grid inherits all of its props from Box. These props are many and repetitive to list, so check out the Grid props on Storybook.

React props
NameTypeDefaultDescription
children  ReactNodeThe content of the Grid
component  ElementTypedivAlternative component used to render, e.g. article, section