Waffle Chart

Installation & usage

npm i @youj/react

For an app already set up with npx @youj/cli init, which installs the peers (@youj/core, @youj/motion, motion and Base UI) and wires the provider. New app? Start at Installation.

Use a waffle chart when a whole splits into a few parts and the count matters as much as the share: waste by source, seats by plan, storage by type. Each cell is one unit, colored by its part, so shares read as areas you could count. For many parts, or parts that differ by orders of magnitude, use a Treemap; for one share in a row, a Share Bar.

import { WaffleChart } from '@youj/react'

<WaffleChart
  label="Waste by source"
  items={[
    { id: 'trim', name: 'Produce trim', value: 22 },
    { id: 'plates', name: 'Plate returns', value: 17 },
    { id: 'bread', name: 'Bread', value: 11 },
  ]}
  formatValue={(v) => `${v} kg`}
/>

unit sets how much one cell counts for, and each part rounds to whole cells. layout="rows" (the default) fills from the top-start corner row by row; layout="cluster" gathers the cells into a round patch at the center, each part a wedge, with empty cells around it. shape="hex" draws hexagons. The grid is columns wide (20 by default) and as tall as it needs, or rows tall; it grows when the cells don't fit. Parts take the chart colors in order unless they set a tone. Say what a cell is next to the chart.

Reference

Propsitems, unit, columns, layout… (9)

Props

WaffleChart props
Prop	Type	Default
`items`Required	`readonly WaffleChartItem[]`	–
`unit`	`number` How much one cell counts for. default 1	`1`
`columns`	`number` Cells across. default 20	`20`
`rows`	`number` Cells down. Default: enough to hold every filled cell, with room around a cluster.	–
`shape`	`'square' \| 'hex'` default 'square'	`'square'`
`layout`	`'rows' \| 'cluster'` `rows` fills from the top-start corner, row by row; `cluster` gathers the cells at the center, each part a wedge. default 'rows'	`'rows'`
`formatValue`	`(value: number) => string` Formats values in the legend's spoken text and the summary. Default: the locale's number format.	–
`label`	`string` Accessible name of the chart. Default: the labels' "Waffle chart".	–
`legend`	`boolean` Show the legend under the cells. default true	`true`
`config`	`Readonly<Record<string, { color?: string }>>` A ChartConfig shared with your other charts: an item whose id is a key takes its color, so one series matches across chart types.	–
Other props pass through: extends `ComponentProps<'div'>`.

StylingParts and data attributes

MotionReveal, new data, lighting a part · reduced motion

Motion

Motion tokens
Moment	Tokens	Value
Revealthe cells fill in order, along the rows or outward from the center for a cluster, when a third of the chart scrolls into view	`duration.deliberateease.standard` 560ms · cubic-bezier(0.2, 0, 0, 1)	560mscubic-bezier(0.2, 0, 0, 1)
New datacells that change part recolor in the same order	`duration.fastease.standard` 140ms · cubic-bezier(0.2, 0, 0, 1)	140mscubic-bezier(0.2, 0, 0, 1)
Lighting a partthe other parts fade back at once, without waiting	`duration.fastease.standard` 140ms · cubic-bezier(0.2, 0, 0, 1)	140mscubic-bezier(0.2, 0, 0, 1)

Reduced motion

Drawn in place; new data lands at once.

Reduced motion

The cells are drawn in place, and new data lands at once.

AccessibilityKeyboard, focus