Grid

Overview

<Grid> renders the .grid of @chassis-ui/css: a display: grid container with twelve columns and, between its items, the gutter of the current breakpoint. <GridItem> places a child on the columns and rows. <Grid> replaces <Row> and <Col>, which version 0.4 removes with the flexbox grid they rendered — see Migrating from Row/Col. The Responsive Grid guide builds page layouts from the pieces documented here. For a single row or column of items, <Stack> and <Flex> are a lighter fit.

Basic usage

Three equal-width columns in a twelve-column grid each span four tracks:

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

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

Item placement

<GridItem> places a child within a <Grid>. An item with no placement props is one track wide and takes the next free cell.

Span

Set span to a number from 1 to 12 to size an item to that many column tracks, rendered as the .col-span-{n} class. An object in place of the number sets the span per breakpoint: base is the span from the narrowest viewport, and a key named after a breakpoint (sm/md/lg/xl/2xl) is the span from that breakpoint up. Every placement prop of <GridItem> takes such an object, as do columns, rows, gap and flow of <Grid>. Three span={{ base: 6, md: 4 }} items span six tracks, and four from the md breakpoint:

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

export const Example = () => {
  return (
    <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>
  )
}

span="full" spans every track of the row (.col-span-full), whatever the column count. An item that stacks below a breakpoint needs it as the base: with a span at md only, the item is one track wide below md, not full width.

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

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

Start

Set start to a column line from 1 to 12 to position an item, independent of the items before it (.col-start-{n}). An offset in the flexbox grid was relative to the previous column; a start line is absolute.

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

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

start="auto" returns an item to the flow, to undo a start line from a breakpoint up:

<GridItem span={6} start={{ base: 4, md: 'auto' }} />

End

Set end to the column line an item ends at, from 1 to 13 (.col-end-{n}): line 13 is the end edge of twelve columns. With span, it places an item against that edge, whatever comes before it.

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

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

end="auto" undoes an end line from a breakpoint up, as start="auto" does a start line.

Rows

Set rows on <Grid> for the number of equal rows in its template: a count from 1 to 6 renders the .grid-rows-{n} class. A grid with no rows has no template rows, and each row is as tall as its content. Place an item on the rows with rowSpan (.row-span-{n}, 1 to 6), rowStart (.row-start-{n}, 1 to 6, or 'auto') and rowEnd (.row-end-{n}, 1 to 7, or 'auto'). All three take a value per breakpoint on an item, as rows does on the grid.

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

export const Example = () => {
  return (
    <Grid rows={2}>
      <GridItem span={4} rowSpan={2}>
        span=4 rowSpan=2
      </GridItem>
      <GridItem span={8}>span=8</GridItem>
      <GridItem span={8} start={5} rowStart={2}>
        span=8 start=5 rowStart=2
      </GridItem>
    </Grid>
  )
}

Columns and gap

columns sets the number of columns and gap the space between items. A column count from 1 to 12 renders the .grid-cols-{n} class, and a Spacing token in gap (the scale <Flex> and <Stack> use) renders the .gap-{token} class. Any other gap is a raw CSS value — a length, or a "{row} {column}" pair — set through the --cx-grid-gap custom property. With no gap, the grid has the gutter of the breakpoint: 1rem below md and 1.5rem from it.

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

export const Example = () => {
  return (
    <>
      <Grid columns={4} gap="1rem">
        <GridItem span={2}>span=2</GridItem>
        <GridItem span={2}>span=2</GridItem>
      </Grid>
      <Grid gap=".25rem 1rem">
        <GridItem span={6}>span=6</GridItem>
        <GridItem span={6}>span=6</GridItem>
        <GridItem span={6}>span=6</GridItem>
        <GridItem span={6}>span=6</GridItem>
      </Grid>
      <Grid gap="lg">
        <GridItem span={4}>span=4</GridItem>
        <GridItem span={4}>span=4</GridItem>
        <GridItem span={4}>span=4</GridItem>
      </Grid>
    </>
  )
}

An object changes columns and gap from a breakpoint up, with the same classes. Only a token fits a breakpoint's gap, since a raw value has no class; base takes either. A breakpoint's columns is a count from 1 to 12 for the same reason.

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

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

The .row-gap-{token} and .column-gap-{token} utilities set one axis, passed through className.

Flow

flow sets the direction a grid places its items in, rendered as the .grid-flow-* classes. A grid fills a row before it starts the next. flow="column" fills the rows of a column before it moves to the next column, so it goes with rows. An object changes the flow from a breakpoint up.

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

export const Example = () => {
  return (
    <Grid columns={2} rows={3} flow="column" gap="md">
      <div>1</div>
      <div>2</div>
      <div>3</div>
      <div>4</div>
      <div>5</div>
      <div>6</div>
    </Grid>
  )
}

flow="dense" moves a later item into a gap that an earlier, wider one left; 'row-dense' and 'column-dense' name the direction too. Below, the third item fits beside the first, where the second did not.

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

export const Example = () => {
  return (
    <Grid columns={3} flow="dense" gap="md">
      <GridItem span={2}>1</GridItem>
      <GridItem span={2}>2</GridItem>
      <GridItem>3</GridItem>
      <GridItem>4</GridItem>
    </Grid>
  )
}

Auto-fill layout

Set fill to render .grid-fill: equal columns, as many as there are children, with no columns to count.

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

export const Example = () => {
  return (
    <Grid fill gap="md">
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
    </Grid>
  )
}

min sets the narrowest a column of a fill grid can get. Children that would be narrower wrap to a new row, so the column count follows the available width with no breakpoint.

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

export const Example = () => {
  return (
    <Grid fill min="10rem" gap="md">
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
      <div>Column</div>
    </Grid>
  )
}

Container queries

A breakpoint key of a prop, such as md in span={{ base: 'full', md: 6 }}, is a width of the viewport. A grid in a sidebar, a panel or a narrow column has less room than the viewport, and a container key follows the room it has: '@sm' to '@2xl' are the widths of sm to 2xl, measured on the nearest query container. <Grid> and <GridItem> take them beside the breakpoint keys and render the container classes of @chassis-ui/css: columns={{ '@md': 3 }} is .@md:grid-cols-3, and span={{ '@md': 4 }} is .@md:col-span-4. Where a breakpoint key and a container key both apply, the container key wins.

A query container is an ancestor with the .contains-inline class. Set contained on the grid for its default gutter and column count to follow that container too. Both boxes below hold the same grid, at any viewport width: the first is 18rem wide, under the @sm width, so its items stack, and the second is 40rem wide, so they sit side by side.

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

const Items = () => (
  <Grid contained>
    <GridItem span={{ base: 'full', '@sm': 4 }}>Item</GridItem>
    <GridItem span={{ base: 'full', '@sm': 4 }}>Item</GridItem>
    <GridItem span={{ base: 'full', '@sm': 4 }}>Item</GridItem>
  </Grid>
)

export const Example = () => {
  return (
    <>
      <div className="contains-inline mb-md" style={{ width: '18rem' }}>
        <Items />
      </div>
      <div className="contains-inline" style={{ width: '40rem' }}>
        <Items />
      </div>
    </>
  )
}

Without a query container above the grid, a container key never applies and contained leaves the gutter of the viewport.

Nesting

A <Grid> inside a <GridItem> is a grid of its own, with twelve tracks across the width of the item. It is narrower than the viewport that the gutter follows, so give it a gap, and columns in place of twelve tracks, or lay it out by its container.

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

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

A nested grid inherits what the outer grid sets through a custom property: a raw gap, min, and a columns above 12. It does not inherit the rest: columns from 1 to 12, rows, flow and a token gap.

Subgrid

Set subgrid on a <GridItem> to give it the column tracks it spans in the parent <Grid> instead of tracks of its own, so its children align to the outer columns. subgrid is a prop of <GridItem> because CSS subgrid only takes effect on an element that is itself a grid item of the parent. A subgrid has a gap and rows of its own: pass it the gap of the parent, or its children are narrower than the parent's tracks.

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

export const Example = () => {
  return (
    <Grid gap="md">
      <GridItem span={8} subgrid gap="md">
        <GridItem span={4}>Subgrid span=4</GridItem>
        <GridItem span={4}>Subgrid span=4</GridItem>
      </GridItem>
      <GridItem span={4}>span=4</GridItem>
    </Grid>
  )
}

Migrating from Row/Col

<Row> and <Col> rendered the flexbox grid, which @chassis-ui/css removed in 0.7. @chassis-ui/react deprecated them in 0.3 and removes them in 0.4. Each of their props has a counterpart on <Grid> and <GridItem>:

Three differences change how a layout behaves:

• An item with no span is one track wide. A bare <Col> shared the row with its siblings, and a <Col> with only a responsive span was as wide as the row below that breakpoint. Give such an item span="full", as the value or the base, or use a fill grid.
• Each prop holds its own breakpoints. <Row> and <Col> took one responsive object, keyed by breakpoint, with the props inside. <Grid> and <GridItem> have no responsive prop: each prop takes an object keyed by breakpoint, with the value below the first one as base. <Grid> and <GridItem> of version 0.3 took the responsive prop too, and their props move the same way.
• The gap applies to both axes. A <Row> with no gutter prop had 1.5rem between columns and nothing between rows. A <Grid> has the gutter of the breakpoint between both; className="row-gap-zero" removes it between rows.
• A start line is absolute. offset pushed a column away from the one before it, so start is the offset plus one only for the first item of a row.

Scope

No content-width tracks. A grid sizes its tracks from the container, not from the content, so <Col span="auto"> has no grid counterpart: a row of items as wide as their content is a <Flex>.

Placement classes stop at twelve columns and six rows. span, start and end render classes that @chassis-ui/css generates up to 12 columns, and rowSpan, rowStart and rowEnd up to 6 rows. In a grid with more, an item past those needs an inline style={{ gridColumn: '…' }}.

No query container of its own. <Grid> makes neither itself nor its parent a query container. The container keys and contained read one from an ancestor, which the layout around the grid provides.

API

Grid

GridItem