Skip to the content

Grid

Grid is the CSS Grid layout container: a <div> with display: grid whose template — columns, rows, named areas and token gaps — is declared in the medias prop. It is layout only; its surface counterpart is Card.
Layout & Surfaces

When to use

Use when
  • Children sit in rows and columns at the same time.
  • You place children in named areas (area="header").
  • The column count changes with the width of the slot or the viewport.
Avoid when
  • Children form a single row or column — use Flex with gap.
  • The block needs a background, border or shadow — use Card or wrap cells in Paper.

Usage

medias is the base template, applied at every width. Each child placed by areas needs its own area prop.

A
B
C
<Grid medias={{ columns: '1fr 1fr 1fr', areas: `"a b c"`, gap: 'small' }}>
  <Paper area="a">A</Paper>
  <Paper area="b">B</Paper>
  <Paper area="c">C</Paper>
</Grid>

medias takes columns, rows, areas, gap, columnGap, rowGap and the alignment keys. A number in columns emits equal tracks that never overflow: 4 → repeat(4, minmax(0, 1fr)).

Responsive templates

The base template is the mobile one. Wider contexts add template keys, in ascending min-width, through two channels:

  • cq — per container size, measured on the nearest ancestor with containment. Without that ancestor the query never matches. Prefer it for components and sections.
  • viewportMedias — per viewport breakpoint, no containment needed. Use it for page shells.

Make the window narrower than 640px to drop to two columns.

1
2
3
4
<Box containment="inline-size">
  <Grid medias={{ columns: 2, gap: 'small' }} cq={{ lg: { columns: 4, gap: 'medium' } }}>
    …
  </Grid>
</Box>

<Grid
  medias={{ columns: '1fr', areas: `"head" "content" "side"` }}
  viewportMedias={{ md: { columns: '160px 1fr', areas: `"head head" "side content"` } }}
/>

The breakpoint-keyed form medias={{ xs: …, md: … }} is deprecated and warns once in development. Move xs to the flat medias base and every other key to viewportMedias, or to cq when the template follows the slot.

Auto-fit columns

{ autoFit: '<min>' } wraps tracks by the space available, with no media query. autoFill keeps empty tracks instead of stretching. The minimum is guarded with min(<min>, 100%), so a track never forces horizontal overflow.

<Grid medias={{ columns: { autoFit: '250px' }, gap: 'medium' }}>
  <Card title="A" />
  <Card title="B" />
  <Card title="C" />
</Grid>

Alignment

Align cells from the grid itself — on the host, in medias or per cq / viewportMedias key — instead of nesting a Flex to center content.

<Grid height={140} alignItems="center" justifyItems="center" medias={{ columns: '1fr 1fr' }}>
  <Paper>centered</Paper>
  <Paper>centered</Paper>
</Grid>

Accessibility

  • Grid renders a <div> with no role. Use as when the region has meaning.
  • areas changes the visual position only. Focus and screen-reader order follow the DOM, so keep the source order logical.

Properties

Grid takes the layout props — spacing, size, position and the layout-only cq / viewportMedias channels, which here also accept the template keys — plus medias, the alignment props, display (default grid) and the native <div> attributes. Annotate a layout object as GridProps when it sets as.

See also