Dot Grid
An activity grid of dots that grow on springs to their level, with changes sweeping across in a diagonal wave.
Preview
"use client";
import { useState } from "react";
import { useAutoplay } from "../demo-context";
import { DotGrid } from "./DotGrid";
const weeks = 16;
const make = (seed: number) =>
Array.from({ length: weeks * 7 }, (_, i) => Math.max(0, Math.round(50 + 45 * Math.sin(i * 0.37 + seed) * Math.cos(i * 0.11 + seed * 2))));
const sets = [make(0), make(1.7), make(3.1)];
export default function Demo() {
const [turn, setTurn] = useState(0);
useAutoplay(() => setTurn((t) => t + 1), 2200);
return <DotGrid label="Commits" values={sets[turn % sets.length]} max={100} summary="16 weeks of activity" color="#14b8a6" />;
}Installation
npx @usefluid/cli add dot-gridpnpm dlx @usefluid/cli add dot-gridyarn dlx @usefluid/cli add dot-gridbunx @usefluid/cli add dot-gridInstall the engine.
Terminal npm i @usefluid/motionCopy these files into your project.
components/fluid/dot-grid/DotGrid.tsx "use client"; import { useSpring } from "@usefluid/motion/react"; import { type CSSProperties, useRef } from "react"; import { levelOf } from "./grid"; import styles from "./DotGrid.module.css"; type Props = { label: string; values: number[]; max?: number; rows?: number; summary?: string; color?: string; }; function Cell({ level, wave }: { level: number; wave: number }) { const dot = useRef<HTMLSpanElement>(null); useSpring( { s: level / 4 }, ({ s }) => { if (dot.current) dot.current.style.transform = `scale(${0.38 + Math.max(0, s) * 0.62})`; }, { w: Math.max(8, 18 - wave * 0.45), z: 0.55 }, ); return <span ref={dot} className={styles.dot} data-level={level} />; } export function DotGrid({ label, values, max, rows = 7, summary, color }: Props) { const top = max ?? Math.max(1, ...values); return ( <figure className={styles.root} style={color ? ({ "--fluid-accent": color } as CSSProperties) : undefined}> <div className={styles.grid} style={{ gridTemplateRows: `repeat(${rows}, auto)` }} role="img" aria-label={summary ? `${label}: ${summary}` : label}> {values.map((v, i) => ( <Cell key={i} level={levelOf(v, top)} wave={Math.floor(i / rows) + (i % rows)} /> ))} </div> <figcaption className={styles.caption}> <span>{label}</span> <span className={styles.scale} aria-hidden> {[0, 1, 2, 3, 4].map((l) => ( <span key={l} className={styles.dot} data-level={l} /> ))} </span> </figcaption> </figure> ); }components/fluid/dot-grid/grid.test.ts import { describe, expect, it } from "vitest"; import { levelOf } from "./grid"; describe("levelOf", () => { it("maps a value to one of five levels against the max", () => { expect([0, 1, 25, 50, 75, 100].map((v) => levelOf(v, 100))).toEqual([0, 1, 1, 2, 3, 4]); }); it("never leaves the range", () => { expect(levelOf(-5, 10)).toBe(0); expect(levelOf(50, 10)).toBe(4); expect(levelOf(3, 0)).toBe(0); }); });components/fluid/dot-grid/grid.ts export function levelOf(value: number, max: number): number { if (!(value > 0) || !(max > 0)) return 0; return Math.min(4, Math.max(1, Math.ceil((value / max) * 4))); }components/fluid/dot-grid/DotGrid.module.css .root { display: grid; gap: 14px; width: min(100%, 520px); margin: 0; padding: 22px; border-radius: 24px; background: var(--fluid-surface); color: var(--fluid-text); font-family: var(--fluid-font); } .grid { display: grid; grid-auto-columns: minmax(0, 1fr); grid-auto-flow: column; gap: 5px; } .dot { display: block; aspect-ratio: 1; border-radius: 999px; background: color-mix(in srgb, var(--fluid-text) 8%, transparent); transition: background 300ms ease; } .dot[data-level="1"] { background: color-mix(in srgb, var(--fluid-accent) 30%, var(--fluid-surface)); } .dot[data-level="2"] { background: color-mix(in srgb, var(--fluid-accent) 55%, var(--fluid-surface)); } .dot[data-level="3"] { background: color-mix(in srgb, var(--fluid-accent) 78%, var(--fluid-surface)); } .dot[data-level="4"] { background: var(--fluid-accent); } .caption { display: flex; align-items: center; justify-content: space-between; color: var(--fluid-text-2); font-size: 13px; } .scale { display: flex; gap: 4px; } .scale .dot { width: 10px; }Import the theme once, then point its variables at your own tokens.
layout.tsx import "@usefluid/motion/theme.css";
Usage
import { DotGrid } from "./DotGrid";
<DotGrid label="Commits" values={dailyCounts} summary="16 weeks of activity" />API reference
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | What the grid shows. Shown under it and used as the accessible name. |
values | number[] | — | One value per dot, filled column by column. Each becomes one of five levels against the max. |
max | number | the largest value | The value of the fullest dot. |
rows | number | 7 | Dots per column: 7 for days of the week. |
summary | string | — | A sentence for screen readers, such as the total or the busiest day. |
color | string | `--fluid-accent` | The colour of the fullest dot; the other levels mix it with the surface. |
Keyboard and screen readers
The grid is an image named with the label and the summary, because hundreds of dots are not useful one by one. With reduced motion dots change at once.
Notes
levelOf in grid.ts maps a value to a level from 0 to 4. Every colour comes from the --fluid-* variables, and the piece is yours to change.
How it is made
Each value becomes one of five levels, and each dot grows to its level on a spring that is slower the further it is from the corner, so a change sweeps across the grid as a wave. The levels mix your colour with the surface. Screen readers get one sentence for the whole grid.
For your agent
For your agent
Add Dot Grid to my project with the Fluid library. Use DotGrid for the activity of my product, one dot per day, with a summary sentence. Read my project first. Use my logo, my colours and my font through the --fluid-* variables. Keep 44px touch targets, visible focus and reduced motion. If I have no SVG logo, ask before making one up.