Loading…

Dither Heatmap

beta

A rows × columns intensity grid drawn in dithered tiles that morph between periods, with a keyboard-navigable cell readout.

Data
1 file
1 npm package
Accessibility notes
Draws on a canvas

Playground

Installation

The CLI installs dither-canvas as well, because this component imports it. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add dither-heatmap

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { HEATMAP } from "@/components/ui/dither-heatmap";

Examples

Every example the tests run, live and operable, side by side.

Default
Activity Dither Heatmap
Gallery
Continuous
With Visible Table
Static

API

Generated from the component's own types, so a prop cannot appear here without existing.

<DitherHeatmap>

Prop	Type	Default
`columns` (required) Column names, start to end (e.g. hours or weeks).	`readonly string[]`	—
`label` (required) What the chart shows. Names the image, the grid and the data table.	`string`	—
`rows` (required) Row names, top to bottom (e.g. weekdays).	`readonly string[]`	—
`values` (required) `values[row][column]`. Missing, negative and non-finite values count as zero.	`readonly (readonly number[])[]`	—
`activeCell` The cell whose readout shows (controlled); null hides it.	`DitherHeatmapCell \| null`	—
`animate`	`boolean`	`true`
`cell` Cell pitch in CSS pixels. Default 3: tiles are small.	`number`	`3`
`color` Colour token or CSS colour expression. Default "primary".	`string`	`"primary"`
`defaultActiveCell`	`DitherHeatmapCell \| null`	`null`
`description` Replaces the generated summary in the image's accessible name.	`string`	—
`formatCell` The readout for one cell. Defaults to "Row, Column: value".	`(cell: DitherHeatmapCellInfo) => string`	—
`formatValue`	`(value: number) => string`	`formatDitherValue`
`lessLabel`	`string`	`"Less"`
`levels` Quantise intensity into this many steps (amicro's activity map uses 5).	`number`	—
`max` Value of a full-intensity tile. Defaults to the largest value.	`number`	—
`moreLabel`	`string`	`"More"`
`onActiveCellChange`	`(cell: DitherHeatmapCell \| null) => void`	—
`rowLabel` Header of the data table's row-name column.	`string`	`"Row"`
`showAxis` Show row and column labels.	`boolean`	`true`
`showLegend` Show a Less → More scale.	`boolean`	`false`
`showTable` Show the data table. It is always present for assistive technology.	`boolean`	`false`
`size`	`"sm" \| "md" \| "lg"`	`"md"`

Plus every attribute of <div> except children.

Accessibility

The plot is role="img" with an aria-label giving its size, total and peak. Over it sits a role="grid" of real gridcells with one roving tab stop: arrow keys move a cell, Home/End go to the row's ends, Ctrl+Home/End to the corners, Escape hides the readout. Each cell's text is its readout, so focus announces what the pointer tooltip shows. Axis labels and the scale legend are aria-hidden; the data is always in a table, visually hidden unless showTable is set.

Quality

Measured from the source and its tests at build time.

All scores

9/9

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Contributions by week

Row

W10

W11

W12

Mon

Tue

Wed

Thu

Fri

Sat

Sun

Prop

Type

Default

columns

Column names, start to end (e.g. hours or weeks).

readonly string[]

—

label

What the chart shows. Names the image, the grid and the data table.

string

—

rows

Row names, top to bottom (e.g. weekdays).

readonly string[]

—

values

values[row][column]. Missing, negative and non-finite values count as zero.

readonly (readonly number[])[]

—

activeCell

The cell whose readout shows (controlled); null hides it.

DitherHeatmapCell | null

—

animate

boolean

true

cell

Cell pitch in CSS pixels. Default 3: tiles are small.

number

3

color

Colour token or CSS colour expression. Default "primary".

string

"primary"

defaultActiveCell

DitherHeatmapCell | null

null

description

Replaces the generated summary in the image's accessible name.

string

—

formatCell

The readout for one cell. Defaults to "Row, Column: value".

(cell: DitherHeatmapCellInfo) => string

—

formatValue

(value: number) => string

formatDitherValue

lessLabel

string

"Less"

levels

Quantise intensity into this many steps (amicro's activity map uses 5).

number

—

max

Value of a full-intensity tile. Defaults to the largest value.

number

—

moreLabel

string

"More"

onActiveCellChange

(cell: DitherHeatmapCell | null) => void

—

rowLabel

Header of the data table's row-name column.

string

"Row"

showAxis

Show row and column labels.

boolean

true

showLegend

Show a Less → More scale.

boolean

false

showTable

Show the data table. It is always present for assistive technology.

boolean

false

size

"sm" | "md" | "lg"

"md"

Row	W1	W2	W3	W4	W5	W6	W7	W11	W12
Mon	30	30	20	20	30	40	30	10	10
Tue	30	30	20	20	30	40	20	10	20
Wed	40	40	20	20	30	30	20	10	20
Thu	40	40	20	20	30	30	20	20	20
Fri	40	40	20	20	20	30	10	20	30
Sat	40	40	20	10	20	20	10	20	30
Sun	40	40	20	10	20	20	10	30	40

Row	W1	W2	W3	W4	W5	W6	W7	W11	W12
Mon	30	30	20	20	30	40	30	10	10
Tue	30	30	20	20	30	40	20	10	20
Wed	40	40	20	20	30	30	20	10	20
Thu	40	40	20	20	30	30	20	20	20
Fri	40	40	20	20	20	30	10	20	30
Sat	40	40	20	10	20	20	10	20	30
Sun	40	40	20	10	20	20	10	30	40

Row	W1	W2	W3	W4	W5	W6	W7	W11	W12
Mon	30	30	20	20	30	40	30	10	10
Tue	30	30	20	20	30	40	20	10	20
Wed	40	40	20	20	30	30	20	10	20
Thu	40	40	20	20	30	30	20	20	20
Fri	40	40	20	20	20	30	10	20	30
Sat	40	40	20	10	20	20	10	20	30
Sun	40	40	20	10	20	20	10	30	40

Row	W1	W2	W3	W4	W5	W6	W7	W11	W12
Mon	30	30	20	20	30	40	30	10	10
Tue	30	30	20	20	30	40	20	10	20
Wed	40	40	20	20	30	30	20	10	20
Thu	40	40	20	20	30	30	20	20	20
Fri	40	40	20	20	20	30	10	20	30
Sat	40	40	20	10	20	20	10	20	30
Sun	40	40	20	10	20	20	10	30	40

Row	W1	W2	W3	W4	W5	W6	W7	W11	W12
Mon	30	30	20	20	30	40	30	10	10
Tue	30	30	20	20	30	40	20	10	20
Wed	40	40	20	20	30	30	20	10	20
Thu	40	40	20	20	30	30	20	20	20
Fri	40	40	20	20	20	30	10	20	30
Sat	40	40	20	10	20	20	10	20	30
Sun	40	40	20	10	20	20	10	30	40

Row	W1	W2	W3	W4	W5	W6	W7	W11	W12
Mon	30	30	20	20	30	40	30	10	10
Tue	30	30	20	20	30	40	20	10	20
Wed	40	40	20	20	30	30	20	10	20
Thu	40	40	20	20	30	30	20	20	20
Fri	40	40	20	20	20	30	10	20	30
Sat	40	40	20	10	20	20	10	20	30
Sun	40	40	20	10	20	20	10	30	40

Row	W1	W2	W3	W4	W5	W6	W7	W11	W12
Mon	30	30	20	20	30	40	30	10	10
Tue	30	30	20	20	30	40	20	10	20
Wed	40	40	20	20	30	30	20	10	20
Thu	40	40	20	20	30	30	20	20	20
Fri	40	40	20	20	20	30	10	20	30
Sat	40	40	20	10	20	20	10	20	30
Sun	40	40	20	10	20	20	10	30	40

Row	W1	W2	W3	W4	W5	W6	W7	W11	W12
Mon	30	30	20	20	30	40	30	10	10
Tue	30	30	20	20	30	40	20	10	20
Wed	40	40	20	20	30	30	20	10	20
Thu	40	40	20	20	30	30	20	20	20
Fri	40	40	20	20	20	30	10	20	30
Sat	40	40	20	10	20	20	10	20	30
Sun	40	40	20	10	20	20	10	30	40