The sheet an infographic is composed on. It paints a full-bleed ground from a poster theme, forces one theme and colour mode on everything inside, and lays out a masthead, a grid of panels and a footer. It can save the whole sheet as one PNG.
Waffle chart
Shows shares of a whole as counted cells in a grid, such as 37 in every 100.
- Use when
- One share ("37 in every 100") or a handful of categories that add up to a whole, where the reader should be able to count the units.
- Avoid when
- Comparing shares across several groups (use bar chart with stack "percent"); more than about 6 categories or shares under 1% (use bar chart); a compact inline part-to-whole (use segmented bar).
Preview
33% of the world's population had never used the internet in 2023
Share of the global population, 2023. Each square is 1% of people
import { WaffleChart } from "insightcharts";
export function Example() {
return (
<WaffleChart
data={[
{ group: "Have never been online", share: 33 },
]}
name="group"
value="share"
total={100}
restLabel="Use the internet"
title="33% of the world's population had never used the internet in 2023"
subtitle="Share of the global population, 2023. Each square is 1% of people"
source="ITU Facts and Figures 2023"
note="Figures are approximate, for illustration"
/>
);
}{
"type": "waffle-chart",
"data": [
{ "group": "Have never been online", "share": 33 }
],
"name": "group",
"value": "share",
"total": 100,
"restLabel": "Use the internet",
"title": "33% of the world's population had never used the internet in 2023",
"subtitle": "Share of the global population, 2023. Each square is 1% of people",
"source": "ITU Facts and Figures 2023",
"note": "Figures are approximate, for illustration"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Composition
Used in
3 molecules and 3 templates use waffle chart.
Molecules
3A share stated as a countable sentence ("37 in every 100…"): a waffle grid or a row of icons beside the statement in large type, with the number emphasised.
Repeats any chart spec once per value of a facet field, each panel with its own filtered rows and a title, in a grid that follows the container width.
Templates
3A graphic that states one fact, at a fixed aspect ratio (1:1, 4:5, 16:9 or 9:16). It has a kicker, a headline, one exhibit, a source and a credit, painted on the theme surface. A button downloads the whole card as a PNG.
A vertical infographic in one narrow column. It opens with a big number or a proportion statement (hook), then the hero exhibit, then numbered sections with one exhibit each, a conclusion with an optional link, and sources.
ThroughProportion statement
A long article read by scrolling. It has a headline, then an ordered list of blocks in a reading column, then a source note. The blocks are prose, figures, charts with a callout, scrolly sequences, pull quotes, stat rows, small multiples and chapter breaks. Exhibits can be wider than the column.
ThroughSmall multiple grid
Installation
$ pnpm dlx shadcn@latest add @insightcharts/waffle-chartThe CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:
import { WaffleChart } from "insightcharts";Examples
Several categories
Coal and gas generated 57.9% of the world's electricity in 2023
Share of global electricity generation by source, 2023
import { WaffleChart } from "insightcharts";
const data = [
{ source: "Coal", twh: 35.4 },
{ source: "Gas", twh: 22.5 },
{ source: "Hydro", twh: 14.3 },
{ source: "Nuclear", twh: 9.1 },
{ source: "Wind", twh: 7.8 },
{ source: "Solar", twh: 5.5 },
{ source: "Other", twh: 5.4 },
];
export function Example() {
return (
<WaffleChart
data={data}
name="source"
value="twh"
format={"{value}%"}
title="Coal and gas generated 57.9% of the world's electricity in 2023"
subtitle="Share of global electricity generation by source, 2023"
source="Ember, Global Electricity Review 2024"
note="Figures are approximate, for illustration"
/>
);
}{
"type": "waffle-chart",
"data": [
{ "source": "Coal", "twh": 35.4 },
{ "source": "Gas", "twh": 22.5 },
{ "source": "Hydro", "twh": 14.3 },
{ "source": "Nuclear", "twh": 9.1 },
{ "source": "Wind", "twh": 7.8 },
{ "source": "Solar", "twh": 5.5 },
{ "source": "Other", "twh": 5.4 }
],
"name": "source",
"value": "twh",
"format": "{value}%",
"title": "Coal and gas generated 57.9% of the world's electricity in 2023",
"subtitle": "Share of global electricity generation by source, 2023",
"source": "Ember, Global Electricity Review 2024",
"note": "Figures are approximate, for illustration"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Highlight, circles
Wind and solar generated 13.3% of the world's electricity in 2023
Share of global electricity generation by source, 2023
import { WaffleChart } from "insightcharts";
const data = [
{ source: "Coal", twh: 35.4 },
{ source: "Gas", twh: 22.5 },
{ source: "Hydro", twh: 14.3 },
{ source: "Nuclear", twh: 9.1 },
{ source: "Wind", twh: 7.8 },
{ source: "Solar", twh: 5.5 },
{ source: "Other", twh: 5.4 },
];
export function Example() {
return (
<WaffleChart
data={data}
name="source"
value="twh"
shape="circle"
highlight={["Wind", "Solar"]}
format={"{value}%"}
title="Wind and solar generated 13.3% of the world's electricity in 2023"
subtitle="Share of global electricity generation by source, 2023"
source="Ember, Global Electricity Review 2024"
note="Figures are approximate, for illustration"
/>
);
}{
"type": "waffle-chart",
"data": [
{ "source": "Coal", "twh": 35.4 },
{ "source": "Gas", "twh": 22.5 },
{ "source": "Hydro", "twh": 14.3 },
{ "source": "Nuclear", "twh": 9.1 },
{ "source": "Wind", "twh": 7.8 },
{ "source": "Solar", "twh": 5.5 },
{ "source": "Other", "twh": 5.4 }
],
"name": "source",
"value": "twh",
"shape": "circle",
"highlight": ["Wind", "Solar"],
"format": "{value}%",
"title": "Wind and solar generated 13.3% of the world's electricity in 2023",
"subtitle": "Share of global electricity generation by source, 2023",
"source": "Ember, Global Electricity Review 2024",
"note": "Figures are approximate, for illustration"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Stress: long names, wide grid, rounding
Survey responses on extending the policy, 1,004 adults
Each cell is 1% of responses. Largest-remainder rounding keeps the grid total at 100
import { WaffleChart } from "insightcharts";
const data = [
{ answer: "Strongly agree that the policy should be extended", n: 333 },
{ answer: "Somewhat agree", n: 333 },
{ answer: "Neither agree nor disagree, or did not answer the question", n: 334 },
{ answer: "Disagree", n: 4 },
];
export function Example() {
return (
<WaffleChart
data={data}
name="answer"
value="n"
rows={5}
columns={20}
height={130}
title="Survey responses on extending the policy, 1,004 adults"
subtitle="Each cell is 1% of responses. Largest-remainder rounding keeps the grid total at 100"
source="Illustrative data"
/>
);
}{
"type": "waffle-chart",
"data": [
{ "answer": "Strongly agree that the policy should be extended", "n": 333 },
{ "answer": "Somewhat agree", "n": 333 },
{ "answer": "Neither agree nor disagree, or did not answer the question", "n": 334 },
{ "answer": "Disagree", "n": 4 }
],
"name": "answer",
"value": "n",
"rows": 5,
"columns": 20,
"height": 130,
"title": "Survey responses on extending the policy, 1,004 adults",
"subtitle": "Each cell is 1% of responses. Largest-remainder rounding keeps the grid total at 100",
"source": "Illustrative data"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| valuerequired | string | Value field. Each category's cells are its share of the whole. | |
| name | string | Category field. Omit for a single share. | |
| total | number | The whole. Default: the sum of the values. Set to 100 with one value to show a single share against an empty remainder. | |
| rows | number | 10 | Grid rows. |
| columns | number | 10 | Grid columns. |
| shape | "square" | "circle" | "square" | Cell shape. |
| restLabel | string | Label for the unfilled remainder when total exceeds the sum. | |
| names | Record<string, string> | Display names for category keys. |
Common chart props 29
Every chart built with defineChart accepts these on top of its own props.
| Prop | Type | Description |
|---|---|---|
| data | DataInput | Rows, CSV text, a URL, { url, path }, an async function, or an Arrow-style table. Omit inside <InsightData>. |
| transform | Transform | Transform[] | A pipeline of transforms applied before drawing. |
| title | string | The title. One plain statement of what the data shows, with the number and the period ("Monthly churn fell from 4.2% to 2.1% in 2024"), or a plain label ("Monthly churn, 2024"). One clause, no figures of speech. |
| subtitle | string | Measure, unit, population, period. |
| source | string | Data source, shown as "Source: ...". |
| note | string | Method notes or caveats. |
| height | number | string | CSS height of the plot. Default 360. |
| aspect | number | Width / height. Overrides height. |
| highlight | string | string[] | The entity (or entities) the title is about. Every other series is drawn in grey. |
| annotations | Annotation[] | Reference lines, shaded bands and callouts, in data coordinates. |
| format | FormatSpec | How to print values: "compact", "percent", "currency:USD", "{value} kg", Intl options, or a function. |
| legend | boolean | Show the legend. Default: shown when there are two or more series. |
| select | boolean | string | Make marks clickable to filter. Inside <InsightData> the selection filters every other chart. Pass a field name, or true to use the chart's category field. |
| onSelect | (values: string[], field: string) => void | Called with the selected values whenever the selection changes. |
| option | EChartsOption | ((option: EChartsOption, ctx: BuildContext) => EChartsOption) | Deep-merged over the generated ECharts option, or a function that receives and returns it. Use it for ECharts settings no prop covers. |
| theme | ThemeInput | A theme, or a partial set of tokens merged over the surrounding theme, for this chart only. |
| mode | ModeInput | "auto" (default) follows the page, "system" follows the OS, or force "light" / "dark". |
| renderer | RendererInput | "auto" (default) uses SVG for light charts and canvas for heavy ones. |
| animate | boolean | Set false to disable animation. Reduced-motion preferences are always respected. |
| lazy | boolean | Mount the chart only when it scrolls near the viewport. Default true. |
| group | string | Link tooltips with other charts sharing this group id. |
| exportable | boolean | ExportFormat[] | Show an export menu: true or a list of formats from png, jpeg, svg, pdf, csv, json. |
| table | boolean | Show a collapsible "View data" table under the chart. |
| alt | string | Accessible description: the chart type and measures, then the main pattern and the notable values. |
| id | string | Stable id for this chart's selection in the shared store. |
| onEvents | Record<string, ChartEventHandler> | ECharts event handlers, e.g. { click: (params, chart) => {} }. Prefix a name with zr: to bind to the canvas itself. |
| onReady | (chart: EChartsInstance) => void | Called with the ECharts instance once it is created. |
| className | string | Class name for the outer <figure>. |
| style | CSSProperties | Inline style for the outer <figure>. |