Interactive Grid Pattern

A decorative grid of `columns × rows` SVG squares (24 × 24 by default) that fills the cell under the pointer. Cells inherit `currentColor`, so `className="text-border"` sets the hue and `lineOpacity` / `hoverOpacity` tune it.

decorativeclientuiv1.2.0

Interactive Grid Pattern — live renderblocks-interactivegridpattern--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/interactive-grid-pattern.json

With the @interlace alias

npx shadcn@latest add @interlace/interactive-grid-pattern

History

This component is at v1.2.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

2 named exports — pull the parts you need.

Public API

import { InteractiveGridPattern, InteractiveGridSquareProps } from '@/components/ui/patterns/interactive-grid-pattern';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

InteractiveGridPattern           (svg — data-slot="interactive-grid-pattern")
    ├─ title                       (tooling only — the root is aria-hidden)
    └─ rect × columns·rows         (data-slot="interactive-grid-square")
                                   (data-active on the hovered cell)

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.

InteractiveGridSquareProps

Prop	Type	Description
position*	{ row: number	—

InteractiveGridPatternProps

Prop	Type	Description
squareWidth	number	Stable selector hook for tests. Required — no runtime default so an omission surfaces in review rather than silently masking it (R5). Each `<rect>` derives `{value}-cell-{index}`. / "data-testid": string; /** Width of a single square, in user-space units. @default 40
squareHeight	number	Height of a single square, in user-space units. @default 40
columns	number	Number of columns in the grid (horizontal squares). @default 24
rows	number	Number of rows in the grid (vertical squares). @default 24
lineOpacity	number	Stroke opacity of every cell's border, 0–1. Combined with the inherited `currentColor` so the consumer controls the hue via a token. @default 0.3
hoverOpacity	number	Fill opacity applied to the hovered cell, 0–1. Combined with the inherited `currentColor` so the consumer controls the hue via a token. @default 0.3
hoveredSquare	number \| null	Controlled active cell. Pass `null` for "none hovered". When set, the component is controlled and `onHoveredSquareChange` is the source of truth (R14). Leave `undefined` to let the component manage hover internally. @default undefined
defaultHoveredSquare	number \| null	Initial active cell for the uncontrolled mode (R14). @default null
squareProps	InteractiveGridSquareProps	Fires when the hovered cell changes — `index` is the flat cell index or `null` when the pointer leaves the grid (R9, noun-first change event). / onHoveredSquareChange?: ( index: number \| null, details: { row: number; column: number } \| null, ) => void; /** Extra props merged onto every `<rect>`, computed per cell (R10).
squaresClassName	string	Class applied to every `<rect>` cell — merged after the base classes.
label	string	Title written into the SVG's `<title>` element. NOT an accessible name: the grid is `aria-hidden`, so nothing here reaches assistive tech. It exists for tooling that reads the SVG on its own — a design handoff, or the file opened directly in a browser. @default "Decorative interactive grid"

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: Animation is gated on prefers-reduced-motion.
ARIA in the source: role="presentation"
aria-hidden

Examples

3 more states from the same story file.

uncontrolledblocks-interactivegridpattern--uncontrolled ↗

controlledblocks-interactivegridpattern--controlled ↗

higher contrastblocks-interactivegridpattern--higher-contrast ↗

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
R4	Extends native el	`Omit<ComponentPropsWithoutRef<'svg'>, 'width'\
R5	testid required, no default	`'data-testid': string` → `{value}-cell-{index}`
R6	data-slot per part	`interactive-grid-pattern` / `interactive-grid-square`
R9	Noun-first change event	`onHoveredSquareChange(index, details)`
R10	Composition seam	`squareProps(index, {row, column})` merges onto each rect
R14	Controlled + uncontrolled	`hoveredSquare` / `defaultHoveredSquare`
R18	Inline style is CSS vars	`--grid-line-opacity` / `--grid-hover-opacity` only
R19	Tokens only	`text-border` + `stroke-current` / `fill-current`
R25	Client component	`useState` + `useId` + `useReducedMotion`

Dependencies

Base UI primitive: Native / no Base UI dependency
Lucide icons: none
NPM dependencies: none
Registry dependencies: @interlace/theme
@interlace/cn
@interlace/use-reduced-motion

Source

The full implementation — components/ui/patterns/interactive-grid-pattern.tsx once installed.

324 lines · TypeScript

github ↗

"use client";

import {
  type ComponentPropsWithoutRef,
  forwardRef,
  useCallback,
  useId,
  useState,
} from "react";

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

/**
 * @interlace/ui — InteractiveGridPattern
 *
 * A decorative grid of `columns × rows` SVG squares (24 × 24 by default) that
 * fills the cell under the pointer. Cells inherit `currentColor`, so

…304 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/interactive-grid-pattern.json