A landscape spread of up to eleven small illustrations of one subject, each a different graphic form, in three bands of unequal panels: a statement in large type, spokes round an icon and a network of circles; a smooth trend with its peak labelled, nested squares and a slope chart; a pill ranking, a treemap, a tile map and sized circles; and a closing row of icon statements.
Stat circles
Shows a few related magnitudes as plain circles sized by area, each with its number set large and a short label.
- Use when
- The poster way to show two to six related magnitudes whose rough proportion is the point: kilograms per person in three countries, the same quantity in three years, a total and its parts set side by side.
- Avoid when
- More than six values or values that need precise comparison (use bar chart); a single number (use big number); many circles of one whole (use circle pack); values close together, where areas look the same (use bar chart or dumbbell chart).
Preview
import { StatCircles } from "insightcharts";
const data = [
{ who: "per person in the United States", kg: 124 },
{ who: "per person in Brazil", kg: 100 },
{ who: "per person in China", kg: 63 },
{ who: "per person in India", kg: 6 },
];
export function Example() {
return (
<StatCircles
data={data}
name="who"
value="kg"
unit="kg"
title="Meat supply in the United States was 124 kg per person in 2021"
subtitle="Meat supply per person per year, kilograms, 2021"
source="FAO food balance sheets"
note="Rounded, approximate figures for illustration"
/>
);
}{
"type": "stat-circles",
"data": [
{ "who": "per person in the United States", "kg": 124 },
{ "who": "per person in Brazil", "kg": 100 },
{ "who": "per person in China", "kg": 63 },
{ "who": "per person in India", "kg": 6 }
],
"name": "who",
"value": "kg",
"unit": "kg",
"title": "Meat supply in the United States was 124 kg per person in 2021",
"subtitle": "Meat supply per person per year, kilograms, 2021",
"source": "FAO food balance sheets",
"note": "Rounded, approximate figures 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 infographics use stat circles.
Infographics
3A poster of one subject by the numbers, in four rows: two figures in large type or as filled silhouettes, two treemaps side by side, a full-width ranking of centred pills with one row highlighted, and packed circles with icons beside a column of sized circles and a closing figure.
A tall poster that is one illustrated scale: a full-height scale-ladder with icons, leader-labelled items and named zones, and a narrow side column of large figures and one small graphic, each set level with the part of the scale it describes.
Installation
$ pnpm dlx shadcn@latest add @insightcharts/stat-circlesThe 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 { StatCircles } from "insightcharts";Examples
Nested, shaded by value
import { StatCircles } from "insightcharts";
const data = [
{ what: "litres to grow one kilogram of beef", litres: 15400 },
{ what: "litres for one kilogram of cheese", litres: 5060 },
{ what: "litres for one kilogram of rice", litres: 2500 },
{ what: "litres for one kilogram of potatoes", litres: 290 },
];
export function Example() {
return (
<StatCircles
data={data}
name="what"
value="litres"
layout="nested"
colorBy="value"
format="integer"
title="One kilogram of beef takes 15,400 litres of water to produce"
subtitle="Water footprint of four foods, litres per kilogram, global average"
source="Water Footprint Network"
note="Rounded, approximate figures for illustration"
/>
);
}{
"type": "stat-circles",
"data": [
{ "what": "litres to grow one kilogram of beef", "litres": 15400 },
{ "what": "litres for one kilogram of cheese", "litres": 5060 },
{ "what": "litres for one kilogram of rice", "litres": 2500 },
{ "what": "litres for one kilogram of potatoes", "litres": 290 }
],
"name": "what",
"value": "litres",
"layout": "nested",
"colorBy": "value",
"format": "integer",
"title": "One kilogram of beef takes 15,400 litres of water to produce",
"subtitle": "Water footprint of four foods, litres per kilogram, global average",
"source": "Water Footprint Network",
"note": "Rounded, approximate figures for illustration"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Steps, with icons, highlight and click to select
import { StatCircles } from "insightcharts";
const data = [
{ year: "trees planted in 2021", trees: 1200 },
{ year: "trees planted in 2022", trees: 2900 },
{ year: "trees planted in 2023", trees: 5100 },
{ year: "trees planted in 2024", trees: 8400 },
];
export function Example() {
return (
<StatCircles
data={data}
name="year"
value="trees"
layout="steps"
icon="tree"
highlight="trees planted in 2024"
select
title="The city planted 8,400 trees in 2024"
subtitle="Street trees planted per year, 2021 to 2024"
note="Illustrative figures for an invented city"
/>
);
}{
"type": "stat-circles",
"data": [
{ "year": "trees planted in 2021", "trees": 1200 },
{ "year": "trees planted in 2022", "trees": 2900 },
{ "year": "trees planted in 2023", "trees": 5100 },
{ "year": "trees planted in 2024", "trees": 8400 }
],
"name": "year",
"value": "trees",
"layout": "steps",
"icon": "tree",
"highlight": "trees planted in 2024",
"select": true,
"title": "The city planted 8,400 trees in 2024",
"subtitle": "Street trees planted per year, 2021 to 2024",
"note": "Illustrative figures for an invented city"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Stress: six circles, long labels, values from 2 to 9,800
import { StatCircles } from "insightcharts";
const data = [
{
item: "tonnes of household waste collected at the kerbside each week across the whole metropolitan area",
t: 9800,
},
{ item: "tonnes sent to the energy-from-waste plant", t: 4100 },
{ item: "tonnes of paper and card recycled", t: 1500 },
{ item: "tonnes of glass", t: 420 },
{ item: "tonnes of small electrical items", t: 35 },
{ item: "tonnes of batteries", t: 2 },
];
export function Example() {
return (
<StatCircles
data={data}
name="item"
value="t"
unit="t"
colorBy="single"
title="The city collects 9,800 tonnes of household waste a week"
subtitle="Household waste by destination, tonnes per week"
note="Illustrative figures for an invented city"
/>
);
}{
"type": "stat-circles",
"data": [
{
"item": "tonnes of household waste collected at the kerbside each week across the whole metropolitan area",
"t": 9800
},
{ "item": "tonnes sent to the energy-from-waste plant", "t": 4100 },
{ "item": "tonnes of paper and card recycled", "t": 1500 },
{ "item": "tonnes of glass", "t": 420 },
{ "item": "tonnes of small electrical items", "t": 35 },
{ "item": "tonnes of batteries", "t": 2 }
],
"name": "item",
"value": "t",
"unit": "t",
"colorBy": "single",
"title": "The city collects 9,800 tonnes of household waste a week",
"subtitle": "Household waste by destination, tonnes per week",
"note": "Illustrative figures for an invented city"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| namerequired | string | Label field: the short text under or beside each circle. | |
| valuerequired | string | Value field: circle area, and the number printed large. Non-positive values are dropped. | |
| unit | string | Unit printed small after each number, e.g. "kg". Leave out when format already includes it. | |
| layout | "row" | "steps" | "nested" | "row" | Circles centred on one line, standing on a shared baseline, or drawn inside each other from a shared lowest point. Narrow containers stack a row or steps into a column. |
| colorBy | "item" | "value" | "single" | "item" | A colour per circle, a shade by value along the sequential ramp, or the accent for all. |
| icon | string | Record<string, string> | Icon above the number in large circles: one for all, or a map from label to icon. Built-in name or path://. |
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>. |