Grid

When to useLink to "When to use"

• Galleries, dashboards and tiles: items that line up in both directions.

Use something else when:

• items run in one direction: Stack (vertical) or Inline (horizontal, wrapping)
• the content is data with headers: a table

UsageLink to "Usage"

import { Grid, GridItem } from "@arshad-shah/cynosure";

<Grid columns={3} gap="6">
  <GridItem span={2}><Chart /></GridItem>
  <Summary />
</Grid>
<Grid columns={{ base: 1, sm: 2, lg: 4 }}>…</Grid>
<Grid columns={2} padding="6">…</Grid>

Columns per breakpointLink to "Columns per breakpoint"

Pass columns an object to choose the column count at each width: { base: 1, sm: 2, lg: 4 } is one column in a narrow grid, two from sm and four from lg. The widths are those of the grid's own content box, not the window's, so the same grid adapts in a page, a side panel, a popup or a shadow root. It is done in CSS alone: nothing is measured by script, server-rendered markup is right on the first paint, and nothing shifts afterwards.

A breakpoint you leave out keeps the count of the one below it. The scale is exported as GRID_BREAKPOINTS. A grid that fills a Container of size sm, md, lg or xl reaches the breakpoint of the same name.

Responsive without breakpointsLink to "Responsive without breakpoints"

Pass minItemWidth and the grid fits as many columns of at least that width as its own width allows, wrapping the rest. Add columns to cap how many there can be. It responds to the grid's width, not the window's, so it works in side panels and popups too. A grid narrower than minItemWidth shows one column the grid's width, never overflowing.

SpanningLink to "Spanning"

Wrap an item in GridItem to span columns (span={2}, or span="full" for the whole row) or rows (rowSpan). A span wider than the grid is clamped to its columns; with columns per breakpoint, to the columns in effect at the current width.

PaddingLink to "Padding"

padding pads all four sides of the grid with a space token. paddingInline (the sides) and paddingBlock (top and bottom) each win over padding for their axis, and "0" counts as a value. The padding is inside the grid's width, and breakpoints measure the room inside it.

<Grid columns={2} padding="6" paddingBlock="8">…</Grid>

In an app shellLink to "In an app shell"

Grid takes grow, shrink, fill, minSize and overflow as Stack does: a grid that takes what a header leaves, may be shorter than its items and scrolls them. GridItem takes overflow, for a wide item that scrolls sideways inside its column.

<Grid columns={2} grow minSize="0" overflow="auto">…</Grid>

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Semantics: Grid is layout only; it adds no role. Render a list with as="ul" and GridItem as="li": bullets and indentation are removed, the list semantics stay.
• Reading order: visual order follows source order, so keyboard and screen reader order match what is seen.
• Direction: columns run with the text direction.
• Nesting: a nested Grid has its own columns and padding and never inherits its parent's.
• Columns per breakpoint: such a grid is a size container (container-type: inline-size), so its width must come from its parent. That is the case in normal block layout and in stretched flex or grid cells; in a shrink-to-fit place (an inline-flex box, a float) give it a width. Spans are clamped for GridItems that are direct children. The breakpoints are in rem, so they follow the page's root font size.

ThemingLink to "Theming"

Grid has no tokens of its own: gaps and padding are the global space tokens (--cy-space-*). The breakpoint widths are fixed (CSS container queries cannot read custom properties).

RelatedLink to "Related"

Stack · Inline · Container · Card