/// Layout
SimpleGrid
A responsive equal-column grid: a base column count plus a per-breakpoint override map, with token-scale spacing.
import { SimpleGrid } from "@protocore/pds";Basics
SimpleGrid splits its children into cols equal-width columns with a token-scale spacing gap. Every cell is the same width, and — following the equal-height row law — the same height.
Responsive columns
Pass a responsive map keyed by breakpoint (xs/sm/md/lg/xl, mirroring the --pds-bp-* scale). Each entry applies from its min-width up and cascades until the next larger override, so you only name the breakpoints that change — no media queries in your app code.
SimpleGrid vs Grid
SimpleGrid is the ergonomic choice when every column is the same width and you think in terms of *how many columns at each breakpoint* — a card wall that goes 1 → 2 → 3 columns as the viewport grows. Reach for Grid when you need an auto-fit track that decides the column count from a min cell width, or fixed non-equal tracks. Under the hood both stretch their children to equal height so surface footers pin to the bottom of the row. spacing is a step on the --pds-space-* scale, never raw pixels.
Usage
Do
- Use SimpleGrid when you think in column counts per breakpoint (1 → 2 → 3).
- Specify only the breakpoints that change in the responsive map; the rest cascade.
- Keep spacing on the token scale.
Don't
- Use SimpleGrid when an auto-fit min-width track (Grid) removes the need to pick counts.
- Pass raw pixel gaps; `spacing` is a step on the token scale (e.g. `spacing={4}`).
- Set a high column count at narrow breakpoints where cells would overflow.
Accessibility
- SimpleGrid is a presentational CSS-grid `<div>` with no role of its own.
- CSS grid does not reorder content, so DOM order (and therefore keyboard/reading order) is preserved.
SimpleGrid props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | — | |
cols | number | 1 | Base column count (applies below the first responsive breakpoint). |
responsive | Partial<Record<SimpleGridBreakpoint, number>> | — | Per-breakpoint column overrides, e.g. `{ sm: 2, md: 3 }`. Each key applies at `min-width` of the matching `--pds-bp-*` step and cascades up until the next larger override, so you only specify the breakpoints that change. |
spacing | enum | 4 | Gap between cells, mapped to `--pds-space-<n>`. |
style | CSSProperties | — |