# SimpleGrid - **Category:** Layout (`layout`) - **Slug:** `layout/simple-grid` - **Status:** stable - **Platforms:** web - **Import:** `import { SimpleGrid } from "@protocore/pds";` - **Docs:** https://pds.protocore.io/components/layout/simple-grid > A responsive equal-column grid: a base column count plus a per-breakpoint override map, with token-scale spacing. ## 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. ## Props | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `className` | `string` | no | — | — | | `cols` | `number` | no | `1` | Base column count (applies below the first responsive breakpoint). | | `responsive` | `Partial>` | no | — | 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` | no | `4` | Gap between cells, mapped to `--pds-space-`. | | `style` | `CSSProperties` | no | — | — | ## Examples ### 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. ```tsx import { SimpleGrid, StatCard } from "@protocore/pds"; export default function SimpleGridBasics() { return ( ); } ``` ### 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. ```tsx import { SimpleGrid, Card } from "@protocore/pds"; export default function SimpleGridResponsive() { const nodes = [ { region: "eu-central-1", status: "healthy" }, { region: "us-east-1", status: "healthy" }, { region: "ap-south-1", status: "degraded" }, { region: "sa-east-1", status: "healthy" }, { region: "af-south-1", status: "healthy" }, { region: "me-south-1", status: "syncing" }, ]; return ( {nodes.map((n) => ( ))} ); } ``` ## Do & don't **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 **Notes** - SimpleGrid is a presentational CSS-grid `
` with no role of its own. - CSS grid does not reorder content, so DOM order (and therefore keyboard/reading order) is preserved. ## Related `grid`, `flex`, `stack`, `container` --- © Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/