<!-- Protocore Design System — Grid -->
# Grid

- **Category:** Layout (`layout`)
- **Slug:** `layout/grid`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { Grid } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/layout/grid

> A CSS grid with either a responsive auto-fit track or a fixed column count, and a token-scale gap.

## When to use it

Use `Grid` for **two-dimensional** layout — anything where items align across both rows and columns. The `auto-fit` mode (default) is a responsive card wall that needs no media queries: set a sensible `min` width and cells reflow on their own. Use a fixed `columns` count only when the layout must not reflow (e.g. a strict 3-up on all sizes). For a single row or column of items, `Stack` is simpler and lighter. Like `Stack`, the `gap` is a token step, not pixels.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` | no | — | — |
| `columns` | `number \| "auto-fit"` | no | `auto-fit` | Fixed column count, or `"auto-fit"` for a responsive minmax track. |
| `gap` | `enum` | no | `4` | Gap between cells, mapped to `--pds-space-<n>`. |
| `min` | `string` | no | `240px` | Minimum column width for the `"auto-fit"` track (ignored for a fixed count). |
| `style` | `CSSProperties` | no | — | — |

## Examples

### Basics

By default `Grid` uses an `auto-fit` track: cells are at least `min` wide and the column count grows to fill the row, wrapping automatically. Ideal for stat and card walls.

```tsx
import { Grid, StatCard } from "@protocore/pds";

export default function GridBasics() {
  return (
    <Grid min="200px" gap={4}>
      <StatCard label="Blocks / s" value="42.7" />
      <StatCard label="Peers" value="1,284" />
      <StatCard label="Mempool" value="8.1k" />
      <StatCard label="Uptime" value="99.98%" />
    </Grid>
  );
}
```

### Fixed columns

Pass a number to `columns` for an exact column count that stays fixed regardless of width.

```tsx
import { Grid, Card } from "@protocore/pds";

export default function GridFixedColumns() {
  const services = ["Gateway", "Indexer", "Relay", "Signer", "Archiver", "Prover"];
  return (
    <Grid columns={3} gap={4}>
      {services.map((s) => (
        <Card key={s} title={s} subtitle="v2.4.1 · running" />
      ))}
    </Grid>
  );
}
```

## Do & don't

**Do**

- Default to auto-fit with a min width for responsive card and stat walls.
- Reserve a fixed columns count for layouts that must never reflow.
- Tune min to the natural minimum width of a cell's content.

**Don't**

- Reach for a fixed count when auto-fit would remove the need for breakpoints.
- Use Grid for a plain single-axis list — Stack is the right tool.
- Set a min so large that a single column overflows narrow viewports.

## Accessibility

**Notes**

- Grid 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.

## Related

`stack`, `container`, `section`, `card`

---

© 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/