Dot Pattern

A resolution-independent dotted-grid background that fills its positioned container. Two render modes share one tiled SVG `<pattern>`:

decorativeclientuiv1.1.0

Dot Pattern — live renderblocks-dotpattern--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/dot-pattern.json

With the @interlace alias

npx shadcn@latest add @interlace/dot-pattern

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

Single named export.

Public API

import { DotPattern } from '@/components/ui/patterns/dot-pattern';

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.

DotPatternProps

Prop	Type	Description
spacingX	number	Horizontal spacing between dot centers, in pixels. @default 16
spacingY	number	Vertical spacing between dot centers, in pixels. @default 16
offsetX	number	Horizontal offset of the whole tile, in pixels — shifts the grid origin. @default 0
offsetY	number	Vertical offset of the whole tile, in pixels — shifts the grid origin. @default 0
dotX	number	Position of each dot within its own cell on the x axis, in pixels. @default 1
dotY	number	Position of each dot within its own cell on the y axis, in pixels. @default 1
radius	number	Radius of each dot, in pixels. @default 1
color	string	Dot color. Accepts any CSS color string, but prefer a design token or `currentColor` so the pattern inherits the surrounding text color — keep raw literals out of consuming source per the token contract. @default "currentColor"
glow	boolean	Animate each dot with a soft radial pulse. Automatically disabled when the user requests reduced motion, falling back to the static tile. @default false

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: aria-hidden

Examples

3 more states from the same story file.

denseblocks-dotpattern--dense ↗

glowblocks-dotpattern--glow ↗

behind contentblocks-dotpattern--behind-content ↗

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
R2	Travels (high)	Pure decoration, zero product nouns — any site can drop it behind a hero
R4	Extends native el + JSDoc	`ComponentPropsWithoutRef<"svg">`; `@default` on every public prop
R5	`data-testid` typed, no default	`"data-testid"?: string` — consumer supplies
R6	`data-slot` on the root	`data-slot="dot-pattern"`
R7	className merged + ...rest + ref	`cn(...)` + `{...props}` + forwarded `ref`
R8	Booleans default-false, no `is`	`glow = false`
R18	Tailwind only	No inline static styles; SVG geometry uses numeric attrs
R19	Tokens only	`currentColor` + the `color` prop; no raw hex / rgb / oklch
R23	CLS=0	`absolute inset-0` decorative chrome; no async height
R25	`"use client"` only as needed	Required — `useId` + motion + reduced-motion hook
R26	a11y	`aria-hidden` + `pointer-events-none`; respects reduced motion

Dependencies

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

Source

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

274 lines · TypeScript

github ↗

"use client";

import {
  type ComponentPropsWithoutRef,
  forwardRef,
  useEffect,
  useId,
  useImperativeHandle,
  useRef,
  useState,
} from "react";

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

/**
 * @interlace/ui — DotPattern (decorative background pattern)
 *

…254 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/dot-pattern.json