Responsive Grid

Overview

The grid system lays content out on twelve columns with <Grid> and <GridItem>. It is built on CSS Grid and follows the viewport through six breakpoints.

import { Container, Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Container>
      <Grid>
        <GridItem span={4}>One of three columns</GridItem>
        <GridItem span={4}>One of three columns</GridItem>
        <GridItem span={4}>One of three columns</GridItem>
      </Grid>
    </Container>
  )
}

Three items of four tracks each make three equal columns at every viewport width. The <Container> around them centers the grid in the page; a grid doesn't need one to work.

Layout primitives

The grid isn't the only layout tool, and two others cover what it isn't the best fit for:

• <Stack> for a single row or column of items, like a button toolbar or the fields of a form.
• <Flex> for items as wide as their content, and for wrapping, justification, and alignment along one axis.

Reach for <Grid> when items share column tracks: page layouts, card grids, and forms whose fields line up across rows.

How it works

The grid system combines breakpoints, containers, a grid, and its items into one layout model:

• The grid follows six breakpoints. Breakpoints are min-width media queries, so a value set for one applies to it and to every wider one: span={{ base: 'full', sm: 4 }} is four tracks from sm up, until another key overrides it.

• Containers center the page and pad its sides. Use <Container> for a width per breakpoint, <Container fluid> for the full width, or <Container fluidUntil="md"> for a mix. The padding of a container is the page margin, separate from the gutter of the grid.

• A grid has twelve columns. <Grid> divides its width into equal tracks. columns changes the count, for the whole grid or from a breakpoint up.

• Items span tracks. <GridItem span={4}> takes four of the twelve. An item with no span is one track wide, so an item that should fill the row takes span="full".

• The gutter follows the breakpoint. With no gap, the space between items is the gutter of the current breakpoint, 1rem below md and 1.5rem from it, in both directions. gap sets another, for the whole grid or from a breakpoint up.

Grid options

The grid adapts across six breakpoints. A layout prop takes one value for every width, or an object with a value per breakpoint, each a key of that object. See Grid options on the CSS site for the width, gutter, and page margin of each.

Equal columns

Columns of the same width need no span on each item: the grid counts them for you, or you give it the count.

As many as children

<Grid fill> gives every child a column of the same width, however many there are. Add min to wrap the children once a column would get narrower than that.

import { Grid } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Grid fill>
        <div>1 of 2</div>
        <div>2 of 2</div>
      </Grid>
      <Grid fill>
        <div>1 of 3</div>
        <div>2 of 3</div>
        <div>3 of 3</div>
      </Grid>
    </>
  )
}

A count per breakpoint

columns sets how many equal columns a grid has, and an object changes the count as the viewport widens: columns={{ base: 1, sm: 2, lg: 4 }}. Further children wrap to the next row. This is what <Row cols> did.

import { Grid } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Grid columns={{ base: 2, md: 3, lg: 5 }} gap={{ base: 'sm', lg: 'md' }}>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
    </Grid>
  )
}

Spans

On the twelve default columns, span gives each item its own width.

All breakpoints

A span with one value holds from the narrowest viewport to the widest.

import { Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Grid>
        <GridItem span={3}>span=3</GridItem>
        <GridItem span={3}>span=3</GridItem>
        <GridItem span={3}>span=3</GridItem>
        <GridItem span={3}>span=3</GridItem>
      </Grid>
      <Grid>
        <GridItem span={8}>span=8</GridItem>
        <GridItem span={4}>span=4</GridItem>
      </Grid>
    </>
  )
}

Stacked to horizontal

Give the items 'full' as the base of their span and a narrower span from a breakpoint up, as in span={{ base: 'full', md: 4 }}, and they start out stacked and sit side by side from that breakpoint. A column count does the same for equal columns: 1 as the base, more from the breakpoint.

import { Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Grid>
        <GridItem span={{ base: 'full', sm: 8 }}>span=full sm:span=8</GridItem>
        <GridItem span={{ base: 'full', sm: 4 }}>span=full sm:span=4</GridItem>
      </Grid>
      <Grid columns={{ base: 1, sm: 3 }}>
        <div>sm:columns=3</div>
        <div>sm:columns=3</div>
        <div>sm:columns=3</div>
      </Grid>
    </>
  )
}

Mix and match

Give a span a base narrower than the row and other spans from a breakpoint up, so that items share a row at every width, in different proportions.

import { Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Grid>
        <GridItem span={{ base: 'full', md: 8 }}>span=full md:span=8</GridItem>
        <GridItem span={{ base: 6, md: 4 }}>span=6 md:span=4</GridItem>
      </Grid>
      <Grid>
        <GridItem span={{ base: 6, md: 4 }}>span=6 md:span=4</GridItem>
        <GridItem span={{ base: 6, md: 4 }}>span=6 md:span=4</GridItem>
        <GridItem span={{ base: 6, md: 4 }}>span=6 md:span=4</GridItem>
      </Grid>
      <Grid>
        <GridItem span={6}>span=6</GridItem>
        <GridItem span={6}>span=6</GridItem>
      </Grid>
    </>
  )
}

Start lines

start puts an item at a column line and leaves the tracks before it empty, which is how you indent or center an item. Unlike the offset of <Col>, a start line counts from the edge of the grid, not from the item before. Don't center a grid item with an auto margin: it shrinks the item to its content.

import { Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Grid>
        <GridItem span={4}>span=4</GridItem>
        <GridItem span={4} start={9}>
          span=4 start=9
        </GridItem>
      </Grid>
      <Grid>
        <GridItem span={{ base: 'full', md: 6 }} start={{ md: 4 }}>
          span=full md:span=6 md:start=4
        </GridItem>
      </Grid>
    </>
  )
}

Gaps

The gap is the space between items, set on the grid and not on the items. There are no negative margins, so a grid never overflows its container the way a row with wide gutters did.

Both axes

gap takes a token of the spacing scale and applies it between columns and between rows. An object changes it from a breakpoint up: gap={{ base: 'sm', lg: 'xl' }}.

import { Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Grid gap={{ base: 'sm', lg: 'xl' }}>
      <GridItem span={6}>gap=sm lg:gap=xl</GridItem>
      <GridItem span={6}>gap=sm lg:gap=xl</GridItem>
      <GridItem span={6}>gap=sm lg:gap=xl</GridItem>
      <GridItem span={6}>gap=sm lg:gap=xl</GridItem>
    </Grid>
  )
}

One axis

The .column-gap-{token} and .row-gap-{token} utilities set one axis each, in place of the gutterX and gutterY of <Row>. row-gap-zero suits items that carry a bottom margin of their own.

import { Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Grid className="column-gap-xl row-gap-2xs">
      <GridItem span={6}>column-gap-xl row-gap-2xs</GridItem>
      <GridItem span={6}>column-gap-xl row-gap-2xs</GridItem>
      <GridItem span={6}>column-gap-xl row-gap-2xs</GridItem>
      <GridItem span={6}>column-gap-xl row-gap-2xs</GridItem>
    </Grid>
  )
}

No gap

gap="zero" removes the space on both axes, for items that should touch.

import { Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Grid gap="zero">
      <GridItem span={{ base: 'full', sm: 6, md: 8 }}>span=full sm:span=6 md:span=8</GridItem>
      <GridItem span={{ base: 6, md: 4 }}>span=6 md:span=4</GridItem>
    </Grid>
  )
}

Content-width columns

A grid sizes its tracks from the container, not from the content. For items as wide as their content beside items that take the rest of the row, use a <Flex> with a gap, and .flex-fill on the items that grow.

import { Flex } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Flex gap="md">
      <div className="flex-fill">Fills the row</div>
      <div>As wide as its content</div>
      <div className="flex-fill">Fills the row</div>
    </Flex>
  )
}

Nested grids

A <Grid> inside an item is a grid of its own, with twelve tracks across the width of the item. The default gutter follows the viewport, not the width of the grid, so in a nested grid — or one in a sidebar or a card — it can be too wide for twelve tracks. Give such a grid a gap and a column count that fits, or let it follow the width of its query container with contained.

import { Grid, GridItem } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Grid gap="md">
      <GridItem span={{ base: 'full', md: 8 }}>
        <Grid columns={2} gap="sm">
          <div>Nested column</div>
          <div>Nested column</div>
        </Grid>
      </GridItem>
      <GridItem span={{ base: 'full', md: 4 }}>span=full md:span=4</GridItem>
    </Grid>
  )
}

To align nested items with the outer columns instead, make the item a subgrid.

API

Container

Grid

GridItem