Grid
CSS grid with column-count presets and token-bound gap. Pass `cols="auto-fit"` + `minColWidth` for responsive grids without media queries.
Installation
pnpm dlx @hex-core/cli add gridUsage
import { Grid } from "@/components/ui/grid"Three-column card grid
Fixed 3 columns with medium gap.
<Grid cols={3} gap="md">
{items.map((i) => <Card key={i.id}>{i.title}</Card>)}
</Grid>Responsive auto-fit
Tracks fit as many 20rem columns as the viewport allows; no media queries needed.
<Grid cols="auto-fit" minColWidth="20rem" gap="lg">
{items.map(...)}
</Grid>API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
cols | "1" | "2" | "3" | "4" | "6" | "auto-fit" | 3 | Number of fixed columns, or `"auto-fit"` for responsive tracks (use with `minColWidth`). |
gap | "xs" | "sm" | "md" | "lg" | "xl" | md | Gap between cells, bound to `--gap-*` tokens. |
align | "start" | "center" | "end" | "stretch" | stretch | Cell vertical alignment within their grid row. |
minColWidth | string | 16rem | Min track size for `cols="auto-fit"` (e.g. `"20rem"`). Ignored when `cols` is a fixed integer. |
AI Guidance
When to use
Use for visually-aligned grids of similar items: card galleries, image walls, dashboard tiles, settings panels. Prefer `cols="auto-fit"` + `minColWidth` over hand-written breakpoints when the column count should adapt to viewport width.
When not to use
Don't use for one-dimensional flows — use `Stack` (vertical) or `Cluster` (horizontal). Don't use for tabular data — use `<table>` or DataTable. Don't fight `Grid` to make uneven columns; if cells need different sizes, use a flexbox layout or a CSS grid with named tracks directly.
Common mistakes
- Setting `cols={5}` and getting nothing — the preset only supports 1/2/3/4/6 (deliberate, to avoid odd visual rhythms); use `cols="auto-fit"` for arbitrary counts
- Passing `cols="auto-fit"` without `minColWidth` — the default `16rem` may not match your design intent
- Using `Grid` for two children when `Cluster` or `Stack` would communicate intent better
Accessibility
Grid is presentational. If the grid renders a list of similar items, wrap in `<ul>`/`<li>` for screen-reader semantics — Grid only handles visual layout.
Token budget: 300