Grid

The 2-D sibling of Stack: a thin, token-bound CSS-grid primitive, not a grid framework. `<Grid>` sets the column track and gap on the foundation `--spacing` scale; `<GridItem>` spans columns, responsively. Two FLAT components rather than one with a `kind…

foundationserveruiv1.1.0

Grid — live renderprimitives-grid--default ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL

npx shadcn@latest add https://ds.interlace.tools/r/grid.json

With the @interlace alias

npx shadcn@latest add @interlace/grid

History

This component is at v1.1.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

No release note names this component yet. It shipped with the release above and has not changed since — see the full changelog for what moved elsewhere in the DS.

Import

4 named exports — pull the parts you need.

Public API

import { Grid, GridItem, gridItemVariants, gridVariants } from '@/components/ui/grid';

Variants

Closed prop unions enforced by class-variance-authority. See Storybook's Variants story for the rendered matrix.

cols
- 1
- 2
- 3
- 4
- 6
- 12
gap
- none
- xs
- sm
- mddefault
- lg
- xl
- 2xl

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

GridProps

Also accepts every <div> attribute. Plus the variant props listed above.

Prop	Type	Description
as	React.ElementType	Render as a different element (e.g. `ul`, `section`). Default `div`.

GridItemProps

Also accepts every <div> attribute. Plus the variant props listed above.

Prop	Type	Description
as	React.ElementType	Render as a different element (e.g. `li`, `article`). Default `div`.

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour: Native element semantics — no interaction layer to get wrong.
Focus ring (WCAG 2.2 SC 2.4.13): Not focusable — no focus indicator required.
Reduced motion: No animation to gate.
ARIA in the source: None — semantics come from the element or the Base UI primitive rather than hand-written ARIA.

Examples

2 more states from the same story file.

responsiveprimitives-grid--responsive ↗

with spanprimitives-grid--with-span ↗

R-rule compliance

Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.

Rule	Concept	Where
R1	New primitive, not a Stack mode	2-D track + span are meaningless on a flex Stack
R4	Extends native el + VariantProps	`React.ComponentProps<'div'> & VariantProps<...>`
R6	data-slot on both parts	`data-slot="grid"` / `"grid-item"`
R7	className merged + ...rest + ref	`cn(variants(...), className)` + `{...props}`
R11	Two flat components, no kind-prop	`Grid` + `GridItem`, not a discriminated union
R18	Tailwind only	zero inline style; static class maps (JIT-safe)
R19	Tokens only	gap→gap-{--spacing}; cols/span→closed unions (R21)
R25	Server component	no hooks → no 'use client'

Dependencies

Base UI primitive: Native / no Base UI dependency
Lucide icons: none
NPM dependencies: class-variance-authority
Registry dependencies: @interlace/theme
@interlace/cn

Source

The full implementation — components/ui/grid.tsx once installed.

167 lines · TypeScript

github ↗

import * as React from 'react';

// @interlace/grid v1.1.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/grid
// What changed since: https://ds.interlace.tools/c/grid#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — Grid / GridItem
 *
 * The 2-D sibling of Stack: a thin, token-bound CSS-grid primitive, not a grid
 * framework. `<Grid>` sets the column track and gap on the foundation
 * `--spacing` scale; `<GridItem>` spans columns, responsively. Two FLAT
 * components rather than one with a `kind: "container" | "item"` union, and
 * both are server components.
 *
 * | Rule | Concept                          | Where in this file                                  |
 * | ---- | -------------------------------- | --------------------------------------------------- |
 * | R1   | New primitive, not a Stack mode  | 2-D track + span are meaningless on a flex Stack    |
 * | R4   | Extends native el + VariantProps | `React.ComponentProps<'div'> & VariantProps<...>`   |

…147 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/grid.json