# InsightCharts

> InsightCharts is an open-source React library of charts, figures, page layouts and infographic posters built on Apache ECharts 6. Components are organised as atoms, molecules and templates. The Infographics set is the templates that draw one designed poster, built from the poster primitives. Every component can be written as JSX or as a JSON spec. Each one carries machine-readable metadata that says when to use it.

This file is the complete agent documentation: 11 guides, then 100 component pages. Index: https://insightcharts.dev/llms.txt

## Quickstart

### Install

```bash
npm install insightcharts echarts
```

`react` (18 or later), `react-dom` and `echarts` (6 or later) are peer dependencies. There is no stylesheet to import: the small amount of CSS the figure chrome needs is injected once at runtime.

To copy component source into your project instead (so you can edit it), use the shadcn registry. The engine still comes from the npm package.

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json
npx shadcn@latest add @insightcharts/bar-chart
```

### A first chart

```tsx
import { BarChart } from "insightcharts";

const data = [
  { country: "Norway", share: 98 },
  { country: "Brazil", share: 89 },
  { country: "Canada", share: 68 },
];

export function Renewables() {
  return (
    <BarChart
      data={data}
      x="country"
      y="share"
      format="{value}%"
      highlight="Norway"
      title="Renewables supplied 98% of Norway's electricity in 2023"
      subtitle="Share of electricity generation from renewables, 2023"
      source="Ember"
    />
  );
}
```

Every chart follows the same shape:

1. `data`: rows (or CSV text, a URL, a function; see the data guide).
2. Field names as strings: `x`, `y`, `series`. No accessors, no functions.
3. Text: `title` (one plain statement of what the data shows, with its number and period, or a plain label), `subtitle` (measure, unit, population, period), `source`, `note`. The rules for writing them are in "Choosing a form".
4. Emphasis: `highlight` names the entity the title is about, and the other series are drawn in grey. `annotations` mark a date, a threshold or a single value.

The chart draws its own title, legend, source line, loading skeleton, error message and empty state ("No data to show."). It sizes to its container; `height` defaults to 360, or pass `aspect` (width divided by height).

### The same chart as JSON

```tsx
import { Insight } from "insightcharts";

<Insight spec={{ type: "bar-chart", data, x: "country", y: "share", title: "Renewables supplied 98% of Norway's electricity in 2023" }} />
```

Use JSX when you are writing a page. Use a spec when the chart is chosen at runtime (by an agent, a CMS, an API). See the JSON spec guide.

### Server and client components

- `insightcharts`, `insightcharts/core`, `insightcharts/story` and `insightcharts/themes` are client modules (the built files start with `"use client"`). In Next.js you can import a chart into a server component and pass it serialisable props.
- `insightcharts/data` is server-safe. Load on the server and pass rows down:

```tsx
import { loadData, transformRows } from "insightcharts/data";
import { LineChart } from "insightcharts";

export default async function Page() {
  const rows = await loadData("https://example.com/energy.csv");
  return <LineChart data={rows} x="year" y="solar" title="Solar generation by year" />;
}
```

- Function props (`onSelect`, `onEvents`, `onReady`, a function `option`, a function `format`, a function `transform`, a function `data`) cannot cross the server/client boundary. Put the chart in a file that starts with `"use client"` when you need them.

### Optional provider

Charts work with no provider. `InsightProvider` sets defaults for everything beneath it, and providers nest.

```tsx
import { InsightProvider } from "insightcharts";

<InsightProvider theme={{ accent: "#7c3aed" }} mode="auto" locale="en-GB" exportable>
  {children}
</InsightProvider>
```

Its props: `theme`, `mode` (`"auto"`, `"system"`, `"light"`, `"dark"`), `renderer` (`"auto"`, `"svg"`, `"canvas"`), `locale`, `animate`, `exportable`, `lazy`.

Defaults: `lazy` is true, so a chart mounts when it scrolls within 200px of the viewport. `renderer="auto"` uses SVG up to about 1,500 marks and canvas beyond. Animation is skipped when the reader prefers reduced motion.

### Custom ECharts options

- `option`: an ECharts option deep-merged over the generated one, or a function `(option, ctx) => option`.
- `onReady(chart)` and a ref (`getInstance()`, `getOption()`, `export()`) give you the ECharts instance.
- `Chart` and `Figure` from `insightcharts/core` render a raw ECharts option inside the same figure chrome when no component fits. Core registers no series types itself, so register the ones you draw: `echarts.use([ScatterChart])` with `echarts` from `insightcharts/core` and `ScatterChart` from `echarts/charts`.

### Components

**Atoms (61)**

- [arc-diagram](https://insightcharts.dev/llms/arc-diagram.md): Places entities in order on a line and joins each related pair with a semicircular arc whose thickness is the value of the connection; dots are sized by each entity's total.
- [area-chart](https://insightcharts.dev/llms/area-chart.md): Shows a quantity over time as a filled area from zero: one series, stacked series, shares of 100%, or a streamgraph.
- [arrow-chart](https://insightcharts.dev/llms/arrow-chart.md): Draws an arrow per category from a start value to an end value, showing the direction and size of each shift.
- [bar-chart](https://insightcharts.dev/llms/bar-chart.md): Compares a value across categories with bars from a zero baseline.
- [beeswarm-chart](https://insightcharts.dev/llms/beeswarm-chart.md): Shows a distribution as one dot per row along a value axis, with dots stacked sideways where they would collide.
- [big-number](https://insightcharts.dev/llms/big-number.md): A featured statistic with its label, change and the context that gives it meaning.
- [block-bar](https://insightcharts.dev/llms/block-bar.md): Compares 3 to 12 values as thick rounded bars from a zero baseline, with each value printed inside the end of its bar and the category beneath.
- [box-plot](https://insightcharts.dev/llms/box-plot.md): Summarises a numeric field per group as median, quartile box, whiskers and outlier dots, computed from raw rows.
- [bubble-network](https://insightcharts.dev/llms/bubble-network.md): Draws a small set of circles sized by value and joined by thin lines, with one circle highlighted and tagged.
- [bubble-scale](https://insightcharts.dev/llms/bubble-scale.md): Places circles sized by one measure along a single value scale set by another, spread sideways so none overlap, with boxed scale marks instead of an axis.
- [bullet-chart](https://insightcharts.dev/llms/bullet-chart.md): Compares one measure per row with its target, optionally against qualitative bands such as poor / fair / good.
- [bump-chart](https://insightcharts.dev/llms/bump-chart.md): Shows how the ranking of entities changes over time, with rank 1 at the top and each line named at its end.
- [calendar-heatmap](https://insightcharts.dev/llms/calendar-heatmap.md): Colours every day of one or more years by a value, laid out as a grid of weeks.
- [callout](https://insightcharts.dev/llms/callout.md): A boxed statement of fact with a short bold lead and a sentence of explanation. The tone is marked by icon and tint.
- [choropleth-map](https://insightcharts.dev/llms/choropleth-map.md): Colours the regions of a map by a normalised value, from GeoJSON you supply.
- [circle-pack](https://insightcharts.dev/llms/circle-pack.md): Shows parts as tightly packed circles sized by value, optionally clustered into groups, with the value and name printed inside each circle.
- [curve-rank](https://insightcharts.dev/llms/curve-rank.md): Places each entity on two parallel scales, one per measure, and joins its two positions with a smooth S-curve labelled with the name and both values.
- [data-table](https://insightcharts.dev/llms/data-table.md): A restrained editorial table from rows and a column config: aligned tabular numbers, an optional in-cell bar, row highlight and click-to-sort headers.
- [delta](https://insightcharts.dev/llms/delta.md): An inline change indicator: direction arrow, signed value and an optional baseline label.
- [diverging-bar-chart](https://insightcharts.dev/llms/diverging-bar-chart.md): Draws bars either side of a centre line: positive against negative values, or stacked agree / disagree responses around a neutral midpoint.
- [donut-chart](https://insightcharts.dev/llms/donut-chart.md): Shows how 2 to 5 parts make up one whole, with each slice labelled by name and share.
- [dumbbell-chart](https://insightcharts.dev/llms/dumbbell-chart.md): Shows two values per category as dots joined by a line, so the length of the line shows the difference.
- [fan-flow](https://insightcharts.dev/llms/fan-flow.md): One solid block that splits into curved ribbons, each as thick as its value, ending at an aligned column of names, values and shares.
- [funnel-chart](https://insightcharts.dev/llms/funnel-chart.md): Shows how many remain at each step of a sequence, with conversion and drop-off between steps.
- [glyph-table](https://insightcharts.dev/llms/glyph-table.md): A table with one row per entity in which every number is drawn as a small form chosen per column (counted dots, squares or icons, a ring, a sized circle, a bar) with the value printed beside it.
- [headline](https://insightcharts.dev/llms/headline.md): The opening block of a piece or section: kicker, title, one-sentence deck and a byline/date line.
- [heatmap](https://insightcharts.dev/llms/heatmap.md): Colours a category-by-category (or time-by-category) grid by a numeric value, using a sequential or diverging scale.
- [histogram](https://insightcharts.dev/llms/histogram.md): Bins a numeric field and shows how many rows fall in each bin, as touching bars on a continuous axis.
- [icon-array-grid](https://insightcharts.dev/llms/icon-array-grid.md): Compares many counts as a grid of labelled tiles, each holding an array of N icons with its name and number.
- [icon-stat](https://insightcharts.dev/llms/icon-stat.md): A "1 in 4"-style statement: a row or grid of simple glyphs with some filled, and the sentence they illustrate.
- [legend-key](https://insightcharts.dev/llms/legend-key.md): A standalone colour key: categorical swatches, or a sequential/diverging ramp with end labels.
- [line-chart](https://insightcharts.dev/llms/line-chart.md): Shows how one or more values change over time or another ordered dimension.
- [lollipop-chart](https://insightcharts.dev/llms/lollipop-chart.md): Ranks categories with a dot on a thin stem from zero, or as a stemless dot plot on a free scale.
- [nested-shares](https://insightcharts.dev/llms/nested-shares.md): Shows several shares of the same whole, such as one share at five dates, as outlines nested from one corner of a square, each enclosing an area equal to its share.
- [orbit-chart](https://insightcharts.dev/llms/orbit-chart.md): Places items as dots on concentric rings round a centre, one ring per category, level or period, with a key that explains rings, angle and dot area.
- [pictogram-chart](https://insightcharts.dev/llms/pictogram-chart.md): Compares quantities with rows of repeated icons, each icon standing for a fixed number of units.
- [pill-rank](https://insightcharts.dev/llms/pill-rank.md): Shows a ranked list as horizontally centred rounded bars, with each name in capitals on its pill, the value at the left edge and the rank at the right.
- [progress-meter](https://insightcharts.dev/llms/progress-meter.md): A labelled horizontal meter of one value against a maximum or target, with the target marked and the value printed.
- [proportional-area](https://insightcharts.dev/llms/proportional-area.md): Compares two to eight values as squares or circles whose areas are proportional to the values, each printed with its name and number.
- [prose](https://insightcharts.dev/llms/prose.md): A readable block of narration at a 45-75 character measure, for the text between charts.
- [pull-quote](https://insightcharts.dev/llms/pull-quote.md): A large quotation with its attribution.
- [radial-bar-chart](https://insightcharts.dev/llms/radial-bar-chart.md): Draws bars around a circle for data that repeats in a cycle, such as hours of the day or months of the year.
- [radial-spokes](https://insightcharts.dev/llms/radial-spokes.md): Draws one spoke per row radiating from a centre disc, each as long as its value, with the name and value set on an outer ring.
- [ribbon-chart](https://insightcharts.dev/llms/ribbon-chart.md): One filled band per entity across periods: its thickness is its value in each period and its vertical position is its rank, so bands cross as the order changes.
- [sankey-chart](https://insightcharts.dev/llms/sankey-chart.md): Shows how a quantity flows from sources through stages to destinations, with link width proportional to the flow.
- [scale-ladder](https://insightcharts.dev/llms/scale-ladder.md): A tall vertical band graded along one scale (linear or log, running up or down) with each item placed at its true position and labelled with an icon, its name and its value on alternating sides.
- [scatter-chart](https://insightcharts.dev/llms/scatter-chart.md): Plots two numeric measures against each other, one dot per row, with optional bubble size, group colour, selective labels and a trend line.
- [segmented-bar](https://insightcharts.dev/llms/segmented-bar.md): Splits one whole into proportional segments along a single horizontal bar.
- [shape-fill](https://insightcharts.dev/llms/shape-fill.md): Shows one or more percentages as icon silhouettes filled from the bottom to that level, with the number printed large beside each.
- [slope-chart](https://insightcharts.dev/llms/slope-chart.md): Connects each entity's value at two (or a few) points with a straight line, labelled with name and value at both ends.
- [small-multiples](https://insightcharts.dev/llms/small-multiples.md): Repeats one small line, area or bar chart per value of a facet field on a shared scale, each panel titled.
- [source-note](https://insightcharts.dev/llms/source-note.md): A sourcing footer for a whole piece: sources with optional links, the period covered, method, caveats and credit.
- [sparkline](https://insightcharts.dev/llms/sparkline.md): A word-sized line or bar series without axes, with the latest point marked.
- [stat-circles](https://insightcharts.dev/llms/stat-circles.md): Shows a few related magnitudes as plain circles sized by area, each with its number set large and a short label.
- [stat-tile](https://insightcharts.dev/llms/stat-tile.md): A compact, bordered KPI tile: label, value, change against a baseline and an optional trend graphic.
- [step-marker](https://insightcharts.dev/llms/step-marker.md): A numbered chapter or step heading ("01 — Electricity sources in 2015") for sequencing the sections of a story.
- [strip-plot](https://insightcharts.dev/llms/strip-plot.md): Shows every observation as a tick or dot along a value axis, one row per category.
- [timeline-chart](https://insightcharts.dev/llms/timeline-chart.md): Places events and spans on a time axis in labelled lanes, with each item named directly.
- [treemap](https://insightcharts.dev/llms/treemap.md): Shows parts of a whole as nested rectangles sized by value, optionally grouped into categories.
- [unit-blocks](https://insightcharts.dev/llms/unit-blocks.md): Shows the size of each group as a solid block of small icons, one icon per fixed number of units.
- [waffle-chart](https://insightcharts.dev/llms/waffle-chart.md): Shows shares of a whole as counted cells in a grid, such as 37 in every 100.

**Molecules (19)**

- [annotated-timeline](https://insightcharts.dev/llms/annotated-timeline.md): A vertical sequence of dated events along a rail, each with a short explanation and, optionally, a small chart or figure.
- [before-after](https://insightcharts.dev/llms/before-after.md): Two states of one measure side by side, as figures or small charts, with the change between them stated in the middle.
- [chart-callout](https://insightcharts.dev/llms/chart-callout.md): A chart with a callout beside it that states the main fact. In narrow containers the callout goes underneath.
- [chart-tabs](https://insightcharts.dev/llms/chart-tabs.md): One chart frame with a segmented control that switches between several views of the same data, morphing between views that share a chart type.
- [comparison-table](https://insightcharts.dev/llms/comparison-table.md): A table whose rows carry inline sparklines, deltas and in-cell bars beside their exact values, from rows and a column config.
- [filter-chips](https://insightcharts.dev/llms/filter-chips.md): The active crossfilter selections of the surrounding `InsightData`, shown as removable chips with a reset control.
- [hero-figure](https://insightcharts.dev/llms/hero-figure.md): The opening exhibit of a piece: kicker, headline and deck above one large chart, with a source line underneath.
- [kpi-grid](https://insightcharts.dev/llms/kpi-grid.md): A responsive grid of trend cards drawn from one dataset: each metric shows its latest value, its change and a sparkline.
- [linked-charts](https://insightcharts.dev/llms/linked-charts.md): Two to four charts over one shared dataset in a responsive grid: clicking a mark in one filters the others, with the active filters shown as removable chips.
- [metric-breakdown](https://insightcharts.dev/llms/metric-breakdown.md): A headline number with its composition underneath: one segmented bar and a key giving each part's value and share.
- [poster](https://insightcharts.dev/llms/poster.md): 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.
- [proportion-statement](https://insightcharts.dev/llms/proportion-statement.md): A 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.
- [quote-figure](https://insightcharts.dev/llms/quote-figure.md): A pull-quote paired with the statistic or small chart that backs it up, side by side and stacking in narrow containers.
- [ranked-list](https://insightcharts.dev/llms/ranked-list.md): A ranking as a list: position, name, value and a thin in-row bar, with an optional change indicator and highlighted rows.
- [scrolly-chart](https://insightcharts.dev/llms/scrolly-chart.md): A scroll-driven story from JSON: one base chart spec and a list of steps, each with narration and a patch of chart props applied while that step is active.
- [section](https://insightcharts.dev/llms/section.md): A story section: a numbered step marker or a headline, introductory prose, then one or more exhibits in a responsive one- to three-column grid.
- [small-multiple-grid](https://insightcharts.dev/llms/small-multiple-grid.md): 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.
- [stat-row](https://insightcharts.dev/llms/stat-row.md): Two to five key figures in one row separated by hairlines, collapsing to two columns and then one as the container narrows.
- [trend-card](https://insightcharts.dev/llms/trend-card.md): A KPI card computed from a series: the latest value, its change against a baseline in the same data, and a sparkline of the series.

**Templates (20)**

- [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md): 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.
- [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md): A compared with B on one page. It has a headline that states the result, the headline figures mirrored either side of their labels, one hero exhibit that shows both sides, paired exhibits on a shared scale, a verdict callout and a source note.
- [count-poster](https://insightcharts.dev/llms/count-poster.md): A poster that counts at scale. Blocks of thousands of unit icons fill most of the sheet, a second band counts reference groups with the same icon at the same size in a muted colour, and a bottom row holds three small graphics: squares sized by area with a ratio bracket, thick bars with the numbers inside, and shares as nested outlines or filled silhouettes.
- [data-explorer](https://insightcharts.dev/llms/data-explorer.md): A set of linked charts over one shared dataset that filter each other. It has a headline, a sentence of instructions with filter chips, a row of figures that recompute from the filtered rows, two to four charts and an optional detail table. It opens on selections the author chooses.
- [executive-brief](https://insightcharts.dev/llms/executive-brief.md): A one-page summary. It has a headline that states the main finding with its number, a deck, a row of three or four key figures, one hero chart with a takeaway callout, two smaller supporting exhibits, a short list of actions and a source note.
- [explainer](https://insightcharts.dev/llms/explainer.md): 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.
- [flow-poster](https://insightcharts.dev/llms/flow-poster.md): A portrait poster of where something comes from and where it goes, in three stacked bands painted in one colour: the producers as large labelled tiles, the leading producer's output fanning out as ribbons to an aligned column of destinations, and the destinations as bubbles on a scale of how much each depends on that producer.
- [matrix-poster](https://insightcharts.dev/llms/matrix-poster.md): One wide landscape graphic that compares 4 to 12 entities on five to seven measures: two measures as S-curves between parallel scales on the left, joined to a table on the right in which every other number is drawn as dots, squares, icons, a ring, a circle or a bar. Both halves share one row order and one colour per entity.
- [network-poster](https://insightcharts.dev/llms/network-poster.md): A poster of who is connected to whom: a full-width arc diagram with one arc per connection, as thick as its value (`arc-diagram`), a strip of two to four large figures, and a bottom row where the same entities return as circles joined by lines (`bubble-network`) and as a ranking of centred pills (`pill-rank`).
- [profile-poster](https://insightcharts.dev/llms/profile-poster.md): A poster that describes one subject from four sides: the subject as one large silhouette filled to a share (`shape-fill`), two to four large figures, its place among other things on one scale (`scale-ladder`), and a table that sets it beside its peers with every number drawn as a small form (`glyph-table`).
- [radial-poster](https://insightcharts.dev/llms/radial-poster.md): A poster with one subject in the middle of the sheet: a wheel of spokes round an icon (`radial-spokes`), two to four large figures standing either side of it, and a bottom row with the same subject's surroundings on concentric rings (`orbit-chart`) and a ranking as centred pills (`pill-rank`).
- [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md): A 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.
- [report-page](https://insightcharts.dev/llms/report-page.md): A section of an analytical report laid out as a document. It has a title block, a summary, numbered findings, then method, limitations and sources. Each finding has one exhibit, an observation and a separately labelled interpretation with a confidence rating and a caveat.
- [scale-poster](https://insightcharts.dev/llms/scale-poster.md): 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.
- [scorecard](https://insightcharts.dev/llms/scorecard.md): A recurring report. It has a masthead with the report name and period, a headline that states the main change, a KPI grid with changes and sparklines, a ranked list beside one or two trend charts, an optional comparison table, short notes and a source note.
- [social-card](https://insightcharts.dev/llms/social-card.md): A 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.
- [story-deck](https://insightcharts.dev/llms/story-deck.md): A sequence of full-frame cards (title, stat, chart, quote, closing) that the reader swipes or steps through. Each card states one fact. It has an optional fixed aspect ratio, a keyboard-accessible pager and a stacked layout for print.
- [timeline-poster](https://insightcharts.dev/llms/timeline-poster.md): A poster of change over a run of periods: a full-width ribbon of bands whose thickness is each entity's value and whose order is its rank (`ribbon-chart`), a strip of two to four dated figures under it, and a bottom row with one measure per period as thick bars (`block-bar`) and one share at several dates as nested outlines (`nested-shares`).
- [timeline-story](https://insightcharts.dev/llms/timeline-story.md): A story told in date order. It has a headline, one overview exhibit of the whole period (a timeline chart or an annotated line), dated chapters along a rail, a closing paragraph and a source note. Each chapter has a short text and an optional small exhibit.
- [visual-essay](https://insightcharts.dev/llms/visual-essay.md): 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.

---

## Choosing a form

First write down the one fact the chart should show, with its number. Then pick the form that shows that fact most directly.

### Decision table

Generated from each component's metadata. Use only names in this table.

| The data's job | Component | Level | Use it when | Pick something else when |
|---|---|---|---|---|
| State one number or one fact | [big-number](https://insightcharts.dev/llms/big-number.md) | atom | A single headline figure, or a row of three or four key numbers. Always give it context: a comparison, a denominator or a period. | Showing a number with no comparison; using a gauge or a one-slice donut for the same job. |
| State one number or one fact | [data-table](https://insightcharts.dev/llms/data-table.md) | atom | When readers need to look up exact values, or compare a handful of entities across several measures with different units. Sort it by the column the caption refers to and highlight the row it names. | Showing a trend or a single comparison (use `line-chart` or `bar-chart`); more than about 7 columns or 30 rows without `maxHeight`. |
| State one number or one fact | [delta](https://insightcharts.dev/llms/delta.md) | atom | Next to a figure, in a sentence, a table cell or a tile, to say how much it changed and against what. Set `upIsGood: false` for measures where a fall is the good news (churn, emissions, wait times). | Standing alone as the main figure (use `big-number` or `stat-tile`, which include a delta). Do not omit the baseline label unless the surrounding text names it. |
| State one number or one fact | [icon-stat](https://insightcharts.dev/llms/icon-stat.md) | atom | A single proportion that is easier to read as people or units than as a percentage: 1 in 4, 3 in 10, 37 of 100. Round to a small denominator first. | Comparing several proportions (use `bar-chart`), precise percentages (use `big-number`), or fractions that need more than 100 units. |
| State one number or one fact | [legend-key](https://insightcharts.dev/llms/legend-key.md) | atom | When several charts (small multiples, a map and a bar chart, a dashboard row) share one colour encoding, show the key once above them and turn their own legends off. | A single chart: its built-in legend or, better, direct labels already do this. Do not list more than eight categories. |
| State one number or one fact | [progress-meter](https://insightcharts.dev/llms/progress-meter.md) | atom | Progress toward a goal, a quota or a capacity: funds raised, budget spent, share of a target reached. Stack several with `size: "sm"` to compare progress across a few items. | Comparing more than a handful of items (use `bar-chart`), anything without a meaningful end point (use `big-number`), or a gauge dial. |
| State one number or one fact | [stat-tile](https://insightcharts.dev/llms/stat-tile.md) | atom | Dashboard grids and KPI rows of three to six figures, each needing its own change indicator or sparkline. Give every tile a delta or a context line. | The single number a story leads with (use `big-number` with `size: "hero"`). Do not put a full chart with axes in the trend slot. |
| Compare values across categories | [arrow-chart](https://insightcharts.dev/llms/arrow-chart.md) | atom | Shifts between two moments across up to about 25 categories when some rise and some fall: swings between elections, before / after a policy. | When both levels matter more than the direction (use dumbbell-chart); more than two points in time (use slope-chart or line-chart); a single value per category (use bar-chart). |
| Compare values across categories | [bar-chart](https://insightcharts.dev/llms/bar-chart.md) | atom | Ranking or comparing up to about 20 categories; grouped for a few series, stacked when the total and its composition both matter. | Change over many time points (use line-chart); two values per category (use dumbbell-chart); more than about 5 stacked segments. |
| Compare values across categories | [bullet-chart](https://insightcharts.dev/llms/bullet-chart.md) | atom | Progress against a target or budget for one to about 10 measures, including measures in different units (`scale: "independent"`); a compact scorecard instead of a row of gauges. | No target or thresholds to compare with (use bar-chart); a single share of a whole (use progress-meter); change over time (use line-chart). |
| Compare values across categories | [diverging-bar-chart](https://insightcharts.dev/llms/diverging-bar-chart.md) | atom | Values that can be above or below zero (net change, balance, deviation from average); survey scales where the split between the two sides matters; two opposed groups back to back. | Values that are all positive (use bar-chart); parts that do not have a natural two-sided order (use a stacked bar-chart); change between two dates (use arrow-chart or dumbbell-chart). |
| Compare values across categories | [dumbbell-chart](https://insightcharts.dev/llms/dumbbell-chart.md) | atom | Before / after or group A / group B across up to about 20 categories, when the size of the difference is what the reader needs. | A single value per category (use lollipop-chart or bar-chart); when the direction of change matters more than the two levels (use arrow-chart); more than two points in time (use slope-chart or line-chart). |
| Compare values across categories | [heatmap](https://insightcharts.dev/llms/heatmap.md) | atom | Finding patterns across two dimensions at once: hour by weekday, cohort by month, product by region. Good when there are too many series for lines or bars and the overall pattern matters more than exact values. | Precise comparison of a few values (use bar-chart); a single series over time (use line-chart); a daily value across a year (use calendar-heatmap). |
| Compare values across categories | [lollipop-chart](https://insightcharts.dev/llms/lollipop-chart.md) | atom | Rankings of 8 to 30 categories where bars would be too heavy; dot plot mode when the values sit far from zero and the differences between them matter, or to compare a few series per row. | Fewer than about 6 categories or part-to-whole stacks (use bar-chart); exactly two values per row where the difference between them matters (use dumbbell-chart); change over time (use line-chart). |
| Compare values across categories | [pictogram-chart](https://insightcharts.dev/llms/pictogram-chart.md) | atom | A few categories (2 to 6) of countable things, people, homes, vehicles, where making the quantity concrete matters more than reading precise values. | More than about 8 categories or values that need precise comparison (use bar-chart); a share of one whole (use waffle-chart); values that would need more than about 60 icons in a row (raise `unit`, or use bar-chart). |
| Show change over time | [area-chart](https://insightcharts.dev/llms/area-chart.md) | atom | A volume or cumulative quantity over time where the filled magnitude matters; stacked when the total and its composition both matter; percent when only the mix matters; stream for the changing mix of many series over a long period. | Comparing the trajectories of several series against each other (use line-chart: only the bottom band of a stack has a flat baseline); a few time points (use bar-chart with stack); more than about 6 bands. |
| Show change over time | [bump-chart](https://insightcharts.dev/llms/bump-chart.md) | atom | League tables over 3 to about 15 periods for up to about 12 entities, when the order and the changes in rank are what matter and the underlying values differ too much (or too little) to share an axis. | When the size of the values matters (use line-chart); only two periods (use slope-chart); a single ranking (use bar-chart or lollipop-chart). |
| Show change over time | [calendar-heatmap](https://insightcharts.dev/llms/calendar-heatmap.md) | atom | Daily data over months or years where weekly rhythm, seasonality, streaks and gaps matter: activity, sales, incidents, habits. | Reading the trend or exact values (use line-chart); fewer than about three months of days (use bar-chart); a non-daily grain such as hour by weekday (use heatmap). |
| Show change over time | [line-chart](https://insightcharts.dev/llms/line-chart.md) | atom | Trends over time with roughly 5 or more points; comparing the trajectories of a few series; one highlighted series against many context series. | Unordered categories (use bar-chart); only two time points (use slope-chart); more than about 6 equally important lines (use small-multiples). |
| Show change over time | [radial-bar-chart](https://insightcharts.dev/llms/radial-bar-chart.md) | atom | Only when the dimension is cyclical and the wrap-around matters: activity by hour of day, seasonality by month, wind by compass direction. The first category is placed at 12 o'clock. | Any dimension that does not wrap around: categories, rankings, years (use bar-chart); precise comparison of values, since bars further out look bigger (use bar-chart or line-chart); more than about 3 stacked series. |
| Show change over time | [slope-chart](https://insightcharts.dev/llms/slope-chart.md) | atom | Before / after for 3 to about 15 entities when the change in level and in ordering both matter; pair with `highlight` to emphasise one line. | Five or more time points (use line-chart); when only the ordering matters (use bump-chart); when only the size of each gap matters (use dumbbell-chart or arrow-chart). |
| Show change over time | [small-multiples](https://insightcharts.dev/llms/small-multiples.md) | atom | The same measure for 4 to about 24 entities when one chart would have too many overlapping lines; pair with `highlight` to pick out one panel, or `context` to show every other line faintly behind each. | Three or fewer series (use line-chart with direct labels); when exact comparison between two entities matters most (use line-chart with `highlight`); a single value per entity (use bar-chart). |
| Show change over time | [sparkline](https://insightcharts.dev/llms/sparkline.md) | atom | Showing the recent history of a number inside a stat tile, a table cell or a sentence, where the shape of the trend matters and exact values do not. | Anything the reader must read values from or compare across series (use line-chart); fewer than about 5 points (state the change in words or use big-number with a delta). |
| Show change over time | [timeline-chart](https://insightcharts.dev/llms/timeline-chart.md) | atom | When things happened and how long they lasted: project phases, terms of office, product launches, the sequence of events in a story. Mix spans (start and end) with point milestones (start only). | A measured value changing over time (use line-chart, with annotations for the events); more than about 40 items (filter, or split into several timelines); durations to be compared precisely with no interest in when (use bar-chart). |
| Show how values are spread | [beeswarm-chart](https://insightcharts.dev/llms/beeswarm-chart.md) | atom | Showing a distribution while keeping every individual visible: 30 to about 2,000 named things (countries, players, schools), optionally in a few rows by group, with one or two highlighted. | More than about 2,000 rows or when only the summary matters (use histogram or box-plot); many groups with few rows each (use strip-plot); two numeric measures (use scatter-chart). |
| Show how values are spread | [box-plot](https://insightcharts.dev/llms/box-plot.md) | atom | Comparing the centre and spread of a numeric value across several groups, especially with many rows per group and an audience comfortable with quartiles. | A general audience or fewer than about 20 rows per group (use strip-plot or beeswarm-chart, which show the observations themselves); one group whose shape matters, such as two peaks, which a box hides (use histogram). |
| Show how values are spread | [histogram](https://insightcharts.dev/llms/histogram.md) | atom | Showing the shape of a distribution for one numeric variable with roughly 50 rows or more: its centre, spread, skew, gaps and multiple peaks. | Comparing distributions across several groups (use box-plot or beeswarm-chart); under about 50 rows, where every observation can be shown (use strip-plot or beeswarm-chart); counts by category (use bar-chart). |
| Show how values are spread | [strip-plot](https://insightcharts.dev/llms/strip-plot.md) | atom | Comparing the spread and clustering of a numeric value across 2 to about 15 categories when there are few enough observations to show each one; many rows with few to a few hundred observations each. | A single group where the shape matters (use histogram or beeswarm-chart); when individual points must be identifiable or coloured (use beeswarm-chart); when only quartiles matter (use box-plot). |
| Show how a total divides | [donut-chart](https://insightcharts.dev/llms/donut-chart.md) | atom | A simple composition with one dominant part, or one part the title is about, where the total itself is worth printing in the centre. | More than 5 categories or parts of similar size that must be ranked (use bar-chart); a single figure (use big-number); composition compared across groups or time (use bar-chart with stack "percent"); a compact card (use segmented-bar). |
| Show how a total divides | [segmented-bar](https://insightcharts.dev/llms/segmented-bar.md) | atom | A compact part-to-whole for cards, table cells and stat rows: budget split, device mix, vote share. The legend carries names in block order. | Comparing compositions across several groups (use bar-chart with stack "percent"); more than about 6 parts or many slivers (use bar-chart); when the reader should count units (use waffle-chart). |
| Show how a total divides | [treemap](https://insightcharts.dev/llms/treemap.md) | atom | Many parts (10 to 100) of very different sizes, or a two-level hierarchy, where the reader needs the largest parts rather than exact comparison: budgets, market capitalisation, export baskets. | Fewer than about 6 parts or values that need precise comparison (use bar-chart); 2 to 5 parts (use donut-chart or segmented-bar); values that can be negative (use bar-chart); change over time (use line-chart). |
| Show how a total divides | [waffle-chart](https://insightcharts.dev/llms/waffle-chart.md) | atom | 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. | 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). |
| Show how two measures relate | [scatter-chart](https://insightcharts.dev/llms/scatter-chart.md) | atom | Showing whether and how two measures move together, spotting clusters and outliers, and placing named entities in a two-dimensional space (with quadrant lines via `annotations`). | A measure over time (use line-chart); one numeric measure by category (use beeswarm-chart or strip-plot); fewer than about 8 points (use bar-chart or a table); more than 4 colour groups (facet with small-multiples). |
| Show movement between stages or groups | [funnel-chart](https://insightcharts.dev/llms/funnel-chart.md) | atom | A strict sequence where each stage is a subset of the one before: sign-up flows, hiring pipelines, sales stages, applications to admissions. 3 to 7 stages. | Stages that are not sequential subsets, or categories with no order (use bar-chart); flows that split to several destinations (use sankey-chart); conversion tracked over time (use line-chart). |
| Show movement between stages or groups | [sankey-chart](https://insightcharts.dev/llms/sankey-chart.md) | atom | Where things come from and where they go: energy from fuel to end use, budget from revenue to spending, users from channel to outcome. Works best with 2 to 4 stages and up to about 20 nodes. | A single sequence of steps with drop-off (use funnel-chart); comparing a few totals (use bar-chart); flows that loop back (cycles cannot be drawn and are dropped); more than about 40 links. |
| Show values by place | [choropleth-map](https://insightcharts.dev/llms/choropleth-map.md) | atom | A rate, share or per-capita figure that varies by place, where the geographic pattern (a north-south divide, a cluster) is what the reader needs to see. Use a diverging scale for change or for values either side of a meaningful midpoint. | Raw counts, which mostly map population (normalise first, or use bar-chart); ranking regions precisely (use bar-chart); a handful of regions with no spatial pattern (use bar-chart); regions so different in size that small ones vanish (use a tile-grid GeoJSON). |
| Draw a poster graphic | [arc-diagram](https://insightcharts.dev/llms/arc-diagram.md) | atom | Connections among up to about 20 entities that have a meaningful order (stops on a line, chapters, age groups, teams by size): trips between stations, trade between neighbours, characters sharing scenes. | Flows with a direction through stages (use sankey-chart); one source splitting into parts (use fan-flow); a full matrix of every pair where exact values matter (use heatmap); more than about 20 entities or 60 connections (use heatmap). |
| Draw a poster graphic | [block-bar](https://insightcharts.dev/llms/block-bar.md) | atom | A short series or ranking that should read as a bold graphic with no axis: ticket sales in each of six years, two paired measures in five regions. Add `detail` for a second small figure above each bar and `marker` for an event between two bars. | More than 12 bars, more than two series or stacked parts (use bar-chart); negative values (use diverging-bar-chart); a long time series (use line-chart); values that differ by more than about 50 times, where the short bars vanish (use proportional-area). |
| Draw a poster graphic | [bubble-network](https://insightcharts.dev/llms/bubble-network.md) | atom | Showing which of up to about 12 named things are connected, and how big each is: trade blocs, route maps between hubs, partnerships, shared ownership. Give `x` and `y` to place the circles by hand, for example roughly geographically. | Flows with magnitudes between stages (use sankey-chart); more than about 12 circles or a dense web of links (use heatmap as a matrix, or data-table); comparison of the sizes alone (use bar-chart or circle-pack). |
| Draw a poster graphic | [bubble-scale](https://insightcharts.dev/llms/bubble-scale.md) | atom | A poster answer to "where does each one sit on this scale, and how big is it": 5 to about 40 named things with a rate or score (the scale) and a magnitude (the area), such as import dependency against share of demand. | Two measures that should be read against each other on two axes (use scatter-chart); one measure only (use beeswarm-chart or strip-plot); precise comparison of the sizes (use bar-chart); more than about 60 rows (use beeswarm-chart). |
| Draw a poster graphic | [circle-pack](https://insightcharts.dev/llms/circle-pack.md) | atom | A poster view of 5 to about 60 parts of very different sizes where the reader should see the largest ones and their rough proportions at once: budgets by programme, emissions by source, users by product. One level of grouping is supported. | Values that need precise comparison (use bar-chart, where bars share a baseline); parts that must visibly add up to a whole (use treemap or waffle-chart); more than about 80 parts (use treemap); negative values (use diverging-bar-chart). |
| Draw a poster graphic | [curve-rank](https://insightcharts.dev/llms/curve-rank.md) | atom | Two different measures of the same 4 to about 15 entities, when the point is how standing on one relates to standing on the other: price against sales, staff against output, cost against usage. Each side has its own scale, stated in its heading. | The same measure at two moments (use slope-chart); ranks across many periods (use bump-chart); more than about 15 entities or a statistical relationship (use scatter-chart); exact comparison on one measure (use bar-chart). |
| Draw a poster graphic | [fan-flow](https://insightcharts.dev/llms/fan-flow.md) | atom | One total divided among 4 to about 14 destinations (or collected from that many origins, with `direction: "in"`) when the picture of the split is the point: where a budget goes, what a day's water is used for, which sources feed one total. | Flows with more than one stage or several sources (use sankey-chart); precise comparison of the parts (use bar-chart); 2 to 4 parts (use segmented-bar or donut-chart); values that can be negative (use bar-chart). |
| Draw a poster graphic | [glyph-table](https://insightcharts.dev/llms/glyph-table.md) | atom | Comparing 3 to about 12 entities across 2 to 5 measures with different units, when the table should read as a graphic: profiles of products, cities, teams or species. Pair it with curve-rank by passing both the same `order`. | Looking up many exact values, sorting, or more than about 12 rows (use data-table); one measure across entities (use bar-chart or pictogram-chart); a trend over time (use line-chart or small-multiples). |
| Draw a poster graphic | [icon-array-grid](https://insightcharts.dev/llms/icon-array-grid.md) | atom | Counts of up to about 150 in 4 to 24 categories, especially rates per 100 or per 1,000: cars per 100 households in 12 districts. Set `total` so every tile shows the same full array with the uncounted icons as ghosts. | Counts in the thousands (use unit-blocks); two to six categories where one row of icons each is enough (use pictogram-chart); values that need precise comparison or ranking (use block-bar or bar-chart); one share of one whole (use waffle-chart). |
| Draw a poster graphic | [nested-shares](https://insightcharts.dev/llms/nested-shares.md) | atom | How much of one whole something was at 2 to 8 dates or in 2 to 8 categories, when the growth of a share is the point: bicycles made 4% of trips in 2005 and 27% in 2025. | Shares that are parts of each other and should add up (use waffle-chart or treemap); more than 8 items or precise reading of a trend (use line-chart); shares within a point or two of each other, where outlines coincide (use block-bar). |
| Draw a poster graphic | [orbit-chart](https://insightcharts.dev/llms/orbit-chart.md) | atom | A designed alternative to a table for 6 to about 40 named things grouped by distance, level or era from one centre: suppliers by tier, moons by planet-distance band, releases by decade, stakeholders by closeness. One item can be highlighted. | A numeric distance that must be read exactly (use strip-plot or scatter-chart); comparison of the dot values (use bar-chart); more than about 6 rings or 40 items (use data-table); hierarchy with sizes that add up (use treemap or circle-pack). |
| Draw a poster graphic | [pill-rank](https://insightcharts.dev/llms/pill-rank.md) | atom | A poster ranking of 4 to about 20 named things where the order and the overall silhouette matter more than fine differences: top cities, largest employers, league tables, with one row highlighted and optional reference rows set apart below. | Precise comparison of values (use bar-chart, where bars share a baseline); negative values (use diverging-bar-chart); change in rank over time (use bump-chart); more than about 25 rows (use data-table). |
| Draw a poster graphic | [proportional-area](https://insightcharts.dev/llms/proportional-area.md) | atom | A few quantities that differ a lot (2 times to 100 times), where the reader should feel the difference in size: lake areas, budgets, market sizes. Nest them to show one quantity inside another. | Values within about 30% of each other, where areas look the same (use block-bar or bar-chart); more than 8 values (use treemap or bar-chart); parts of one whole (use treemap or waffle-chart); negative values. |
| Draw a poster graphic | [radial-spokes](https://insightcharts.dev/llms/radial-spokes.md) | atom | A poster of 4 to 12 effects, causes or attributes of one subject, which sits in the centre as an icon or a short label: what a household's energy goes on, the side effects of one drug, the scores of one product. | Precise comparison or a ranking (use bar-chart or pill-rank); a dimension that is a cycle, such as hours or months (use radial-bar-chart); more than 12 rows (use bar-chart); several subjects compared on the same attributes (use small-multiples or heatmap). |
| Draw a poster graphic | [ribbon-chart](https://insightcharts.dev/llms/ribbon-chart.md) | atom | 4 to 8 entities over 4 to 10 periods when both the size of each and the changing order matter, and the graphic should read as one flowing form: market shares, harvests, medal tables, budget lines. | Totals that matter more than order, or a smooth centred stream of many periods (use area-chart, which has stacked and stream modes); rank alone (use bump-chart); more than 8 entities or 10 periods (use line-chart or small-multiples); values that can be negative (use line-chart). |
| Draw a poster graphic | [scale-ladder](https://insightcharts.dev/llms/scale-ladder.md) | atom | Answering how deep, how high, how hot, how old or how far each of 4 to about 20 things is on one shared scale, when the reader needs the positions themselves: depths, altitudes, temperatures, ages, distances. Use `zones` to name ranges along the scale. | Comparing sizes rather than positions (use bar-chart or lollipop-chart); events with start and end dates (use timeline-chart); a distribution of many unnamed values (use strip-plot or histogram). |
| Draw a poster graphic | [shape-fill](https://insightcharts.dev/llms/shape-fill.md) | atom | One to six shares of a full amount where the object itself says what is measured: how full a reservoir is, how charged a fleet is, what share of homes have a heat pump. | The fill height only approximates the share, because an irregular silhouette holds less area at its narrow end, so the number must always stay printed; for values to be compared precisely use block-bar or bar-chart, for a counted share use waffle-chart, for a compact inline meter use progress-meter. |
| Draw a poster graphic | [stat-circles](https://insightcharts.dev/llms/stat-circles.md) | atom | 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. | 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). |
| Draw a poster graphic | [unit-blocks](https://insightcharts.dev/llms/unit-blocks.md) | atom | Large counts of people or things in 2 to 12 groups, where the reader should see the crowd itself: 20,350 marathon finishers by age group, one figure per 10 runners. | Precise comparison of close values (use block-bar or bar-chart); fewer than about 30 icons per group (use pictogram-chart or icon-array-grid); shares of one whole (use waffle-chart). |
| Draw a poster graphic | [poster](https://insightcharts.dev/llms/poster.md) | molecule | Use it as the outer frame of any infographic: one dominant graphic with a few supporting panels, on a painted ground. Give it a poster theme (`noir`, `magenta`, `dusk`, `paper`, `ocean`, `forest`, `blueprint`, `sunrise`) and put a chart or figure spec in each panel. Put the one fact in `title` and keep panel headings short. It reflows to one column under 600px. | Long reading text or more than about six panels (use `report-page` or `visual-essay`). A single fact at a fixed social size (use `social-card`). Charts that need axes, gridlines and dense labels to be read, because a poster ground suits large flat marks with their values printed on them. |
| Lay out a whole poster | [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md) | template | Use it when one subject has many small facts of different kinds (shares, places, a trend, a change, a ranking, a map) and none of them should dominate: a crop, an industry, a service, a country's internet. Fill at least eight regions. Give every panel a short heading that states its one number. Every region is optional, and each band shares its width among the panels that are present. | One dominant fact or graphic (use `count-poster`, `flow-poster` or `ranking-poster`). The same measures across several entities (use `matrix-poster`). Fewer than six panels (use `poster` and place them yourself). A phone-first piece: the spread becomes one long column under 600px. |
| Lay out a whole poster | [count-poster](https://insightcharts.dev/llms/count-poster.md) | template | Use it when the subject is a large count of people or things in 2 to 6 groups and the reader should see the crowd: pupils by stage, trees planted by species, vehicles built by model. Give `hero` the groups and `reference` one to three quantities to compare them with. Both bands use the same `unit`, `icon` and icon size, so their areas compare. State the total in the title. | Counts under a few hundred (use `pictogram-chart` in a `poster`). Shares of one whole as the main point (use `waffle-chart` or `treemap`). A ranking of many named things (use `ranking-poster`). A flow from sources to destinations (use `flow-poster`). |
| Lay out a whole poster | [flow-poster](https://insightcharts.dev/llms/flow-poster.md) | template | Use it when one producer leads and the reader should follow its output: ports and the buyers of one port's catch, regions and the users of one region's electricity, terminals and the routes out of the largest. Give `producers` 4 to 10 rows, `flow` 4 to 12 destinations of the leading producer, and `scale` the same destinations with a share (position) and a size. Keep the destination names identical in `flow` and `scale` so `linked` can join them. | Flows through more than one stage or between many sources and many destinations (use `sankey-chart` in a `poster`). A count of people or things (use `count-poster`). Many measures of the same entities (use `matrix-poster`). |
| Lay out a whole poster | [matrix-poster](https://insightcharts.dev/llms/matrix-poster.md) | template | Use it for profiles of a handful of comparable things with measures in different units: cities, species, products, stations, teams. Pass one row per entity with every measure in it. Put the two measures whose relationship matters in `curve` and the rest in `columns`, choosing a counted glyph (`dots`, `blocks`, `icons`) for small whole numbers, `ring` for shares, `bar` or `circle` for magnitudes. Leave `highlight` out to give every entity its own colour, derived from the theme when its palette is smaller than the number of entities; set it to draw one or two entities in colour and the rest in grey. | One measure across entities (use `pill-rank` or `bar-chart`). More than 12 entities (use `data-table` or `heatmap`). A subject with a total and its parts (use `ranking-poster` or `flow-poster`). A phone-first piece: the table stacks into cards under 600px and the poster becomes long. |
| Lay out a whole poster | [network-poster](https://insightcharts.dev/llms/network-poster.md) | template | Use it when the connections between 5 to about 20 named things are the subject: ferry crossings between harbours, joint papers between institutes, freight between rail yards. Give `hero` one row per connection and the `order` the entities sit in, `map` the entities with a size and optional hand-placed `x` and `y`, and `rank` one measure of each entity. With `linked`, a click on an entity in any of the three highlights it in the other two. | A flow from sources to destinations in one direction (use `flow-poster` or `sankey-chart`). More than about 20 entities or 40 connections, because the arcs cover each other. Entities with no meaningful order and few links (use `bubble-network` in a `poster`). Parts of one subject (use `radial-poster`). |
| Lay out a whole poster | [profile-poster](https://insightcharts.dev/llms/profile-poster.md) | template | Use it for a fact sheet about one named thing: a vehicle, a reservoir, a building, a machine, a species. Give `portrait` one row with the share that defines the subject and the `icon` that stands for it, `figures` the numbers a reader should take away, `scale` the subject among 4 to 10 reference points, and `table` the subject beside 2 to 6 peers. Highlight the subject in `scale` and `table`. On a sheet at least 960px wide the silhouette, the figures and the scale stand in three columns. | Several subjects of equal weight (use `glyph-table` in a `poster`, or `ranking-poster`). A subject whose parts are the point (use `radial-poster`). A subject with no defining share: leave `portrait` to a full spec such as `stat-circles`, or use `scale-poster` when the scale is the whole subject. Change over time (use `timeline-poster`). |
| Lay out a whole poster | [radial-poster](https://insightcharts.dev/llms/radial-poster.md) | template | Use it when the poster is about the 4 to 12 parts, causes, effects or scores of one thing: what a household's water goes on, the species one tree supports, where one home's energy goes. Give `hero` the spokes and an `icon` for the centre, state the total in the title, and use `figures` for the two to four numbers a reader should take away. | Parts of a whole that must be compared precisely (use `bar-chart` in a `poster`). Positions on one scale (use `scale-poster`). Change over time (use `timeline-poster`). Connections between many things (use `network-poster`). Large counts shown as crowds (use `count-poster`). |
| Lay out a whole poster | [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md) | template | Use it for a profile of one event, place or organisation that has a headline total, two ways to split it, a ranking of 6 to 12 named things and a few supporting magnitudes: a festival, a race, a nature reserve, a library service. Put the total in the title and repeat it as the first figure. Highlight the ranking row the heading is about. | A subject whose point is a count of people or things (use `count-poster`). Several entities compared on the same measures (use `matrix-poster`). Eight or more small graphics on one subject (use `atlas-poster`). A ranking alone (use `pill-rank` in a `poster`). |
| Lay out a whole poster | [scale-poster](https://insightcharts.dev/llms/scale-poster.md) | template | Use it when the positions of 6 to about 16 named things on one scale are the whole subject: depths, altitudes, temperatures, distances, ages. Give the scale's rows and zones in `scale`, up to five `figures` with the scale position each belongs to, and optionally a `side` graphic of two to four magnitudes. Beside the scale the figures line up with their positions; under 760px they move below it. | Comparing sizes rather than positions (use `ranking-poster` or `count-poster`); change over time (use `timeline-poster`); more than about 16 items, because the labels run together; several unrelated graphics (use `poster` and lay the panels out yourself). |
| Lay out a whole poster | [timeline-poster](https://insightcharts.dev/llms/timeline-poster.md) | template | Use it when the subject is how 4 to 8 named things grew, shrank and changed places over 4 to 10 periods: electricity by source, library loans by format, commuters by mode. Give `hero` the periods and entities, `milestones` the dated numbers a reader should take away, `bars` one measure of the whole at each period and `shares` one share at a few dates. State the latest value in the title. | A single series over time (use `line-chart` or `area-chart` in a `poster`). Events with start and end dates (use `timeline-chart` or the `timeline-story` template). More than 8 entities or 10 periods, because the bands get too thin to label. Positions on one scale (use `scale-poster`). Parts of one subject at one date (use `radial-poster`). |
| State something in words | [callout](https://insightcharts.dev/llms/callout.md) | atom | Beside or under a chart, to state its main fact in words, with the number. Also for a caveat the reader must not miss (`negative`). | Long narration (use `prose`), a featured number (use `big-number` or `stat-tile`), or more than one callout per chart. |
| State something in words | [headline](https://insightcharts.dev/llms/headline.md) | atom | At the top of a data story (`page`), at the start of each chapter (`section`), or as the heading of a tile (`card`). Write the title as one plain fact with its number. Write the deck as a second plain sentence. | Titling a single chart: charts carry their own `title` and `subtitle`. For numbered chapters use `step-marker`. |
| State something in words | [prose](https://insightcharts.dev/llms/prose.md) | atom | To say what a chart showed and introduce the next one. Use two or three short paragraphs at a time. | A single statement of fact (use `callout`), a quotation (use `pull-quote`), or sourcing and method notes (use `source-note`). |
| State something in words | [pull-quote](https://insightcharts.dev/llms/pull-quote.md) | atom | To quote a person on a finding the charts have already shown, or to break up a long run of charts. One per section at most. | Restating a number (use `big-number`) or the main fact of a chart (use `callout`). Never quote without attribution. |
| State something in words | [source-note](https://insightcharts.dev/llms/source-note.md) | atom | Once, at the end of a story or dashboard, to say where every number came from and how it was produced. | Sourcing a single chart: use that chart's own `source` and `note` props so the citation travels with its export. |
| State something in words | [step-marker](https://insightcharts.dev/llms/step-marker.md) | atom | When a piece has three to seven ordered chapters or steps. Open each one with a marker so the reader can see the position in the sequence. | Unordered sections (use `headline` with `size: "section"`), or numbering a list of items inside a paragraph. |
| Arrange several pieces | [before-after](https://insightcharts.dev/llms/before-after.md) | molecule | A single measure at two moments or under two conditions: before and after a policy, control and treatment, last year and this. The change is computed from the two values unless you state it. | More than two states (use `line-chart` or `slope-chart`); many entities each with a before and after (use `dumbbell-chart` or `arrow-chart`); two unrelated figures (use `stat-row`). |
| Arrange several pieces | [chart-callout](https://insightcharts.dev/llms/chart-callout.md) | molecule | Whenever a chart needs its meaning stated in words next to it: the standard chart-plus-interpretation unit of a report. The chart's title states the main fact with its number. The callout adds a second fact, a cause or a caveat in plain words. | Repeating the chart title in the callout; long narration (put `prose` before the chart instead); a chart that is already a small tile (the callout would outweigh it). |
| Arrange several pieces | [chart-tabs](https://insightcharts.dev/llms/chart-tabs.md) | molecule | The same entities under two to five measures or scalings where each view changes the reading: total / per capita / change, absolute / share, linear / log. Give the frame a plain label as its title. Each view's `subtitle` names its measure. | Hiding the most important view behind a tab (show it first, or show both with `small-multiple-grid`); unrelated charts (give each its own figure); more than five views. |
| Arrange several pieces | [comparison-table](https://insightcharts.dev/llms/comparison-table.md) | molecule | Comparing five to twenty entities on a level, a trend and a change at once: countries, products, teams. Readers look up their row. The sparkline and delta show how the value changed. | Plain lookups with no series (use `data-table`); one measure ranked (use `ranked-list` or `bar-chart`); trends the reader must compare precisely (use `small-multiples`). Each sparkline has its own scale, so it shows the direction of change and cannot be used to compare levels between rows. |
| Arrange several pieces | [filter-chips](https://insightcharts.dev/llms/filter-chips.md) | molecule | Inside any `<InsightData>` whose charts use `select`: put it above the charts so readers can see what is filtered, drop one value, or clear everything. `linked-charts` already includes it. | Outside `<InsightData>` it renders nothing unless you pass `selections` yourself. It is not a filter builder: selections are made by clicking marks in the charts. |
| Arrange several pieces | [kpi-grid](https://insightcharts.dev/llms/kpi-grid.md) | molecule | The top of a dashboard or a monthly report: three to eight metrics tracked over the same periods. Pass one table with a column per metric. | Figures without a series behind them (use `stat-row`); comparing the metrics with each other on one scale (use `line-chart` or `small-multiples`); more than eight cards. |
| Arrange several pieces | [linked-charts](https://insightcharts.dev/llms/linked-charts.md) | molecule | Exploration of one table along several dimensions: by region, by category and over time. Pass row-level data once; each chart aggregates it with its own `transform`, sets `select: true` and omits `data`. | A report that states one fixed fact (use `chart-callout` or `scrolly-chart`); charts over unrelated datasets (they cannot filter each other); more than four charts. |
| Arrange several pieces | [metric-breakdown](https://insightcharts.dev/llms/metric-breakdown.md) | molecule | A total that the reader will immediately want split: a budget by department, revenue by product line, emissions by sector. Two to six parts that add up to the number above them. | Parts that do not sum to the headline; more than about six parts (use `bar-chart`); composition compared across groups or over time (use `bar-chart` with `stack: "percent"` or `area-chart`). |
| Arrange several pieces | [ranked-list](https://insightcharts.dev/llms/ranked-list.md) | molecule | A top-N list where the names matter as much as the values: league tables, best and worst performers, leaderboards with a movement column. It keeps long names readable and works in a narrow column. | Precise visual comparison of many values or more than about 15 rows (use `bar-chart`); several measures per entity (use `data-table` or `comparison-table`); rank changing over time (use `bump-chart`). |
| Arrange several pieces | [small-multiple-grid](https://insightcharts.dev/llms/small-multiple-grid.md) | molecule | Faceting a chart form the `small-multiples` atom does not draw: stacked bars, scatter plots, donuts, waffles, dumbbells, histograms. Also when each panel should be a full chart with its own tooltip and axis. | Line, area or bar facets that must share one value scale: use the `small-multiples` atom, which draws every panel in one chart on a common axis. Here each panel scales to its own rows unless the spec fixes the axis (for example `option: { xAxis: { max: 70 } }`), so say so in the subtitle or fix it. More than about twelve panels. |
| Arrange several pieces | [stat-row](https://insightcharts.dev/llms/stat-row.md) | molecule | The opening summary of a report or dashboard: the two to five most important numbers. Give every figure a delta or a context line, and order them by importance. | More than five figures (use `kpi-grid`), a single lead number (use `big-number` with `size: "hero"`), or figures that need their history shown (use `kpi-grid`, or `variant: "tiles"` with a `trend`). |
| Arrange several pieces | [trend-card](https://insightcharts.dev/llms/trend-card.md) | molecule | A metric whose recent history matters as much as its level: users, revenue, response time. Pass the series and field names; the figure, the change and the sparkline all come from the same rows, so they cannot disagree. | A number with no history (use `big-number` or `stat-tile`); several metrics from one dataset (use `kpi-grid`); a series the reader must read values from (use `line-chart`). |
| Arrange several pieces | [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md) | template | Use it for two things a reader has to choose between or compare, such as two countries, two products or a before and an after. Write the result with its number in the headline. Put the four or five most important measures in `figures`. Use a two-series line, dumbbell, slope or `before-after` as the hero. In each pair, use the same chart form and the same scale for both sides. The `subject` side takes the accent colour everywhere and the other side stays grey. | Three or more things (use a `comparison-table` or `small-multiple-grid` inside a `report-page`). One thing over time with nothing to compare it with (use `timeline-story`). Paired charts on different scales, because readers compare bar lengths across the pair. |
| Arrange several pieces | [executive-brief](https://insightcharts.dev/llms/executive-brief.md) | template | Use it when a decision-maker will spend about a minute on the page. State the main finding with its number and period in the headline. The headline and the hero chart should be enough for a reader who stops there. The figures, supporting exhibits and actions add detail. Use one accent colour for the subject (`highlight`) and leave everything else grey. Mark the cause on the hero as an annotation. The proportions suit a printed page. | More than one hero or more than three supporting exhibits (use `report-page`). A recurring set of numbers with no single finding (use `scorecard`). A story told in several steps (use `visual-essay`). |
| Arrange several pieces | [report-page](https://insightcharts.dev/llms/report-page.md) | template | Use it for readers who will check the reasoning, as in evaluations, research notes, audits and experiment write-ups. State the main finding with its number in the title. Put all the main findings and the recommendation in the summary. Write each finding title as one fact with its number, and give it an exhibit that shows that fact. Put what the data shows in `observation` and what you infer from it in `interpretation`. End with method, limitations and sources. | A decision-maker who wants only the result (use `executive-brief`). A general audience (use `explainer` or `visual-essay`). Findings without an exhibit. Put those in the summary. |
| Arrange several pieces | [scorecard](https://insightcharts.dev/llms/scorecard.md) | template | Use it for weekly or monthly numbers. Keep the layout the same in every edition so readers know where each number is. Change the headline each edition to state the main change with its number. The headline and the KPI row should be enough for a reader who stops there. The ranking, trends and notes add detail. Highlight the one row or series the headline is about and leave the rest grey. | A one-off finding (use `executive-brief`). Readers who need to filter the data themselves (use `data-explorer`). More than six KPIs. |
| Arrange several pieces | [social-card](https://insightcharts.dev/llms/social-card.md) | template | Use it for one finding that will be shared in a feed, a slide or a chat thread with no text around it. State the fact with its number in the headline. Use one simple exhibit, such as one highlighted bar, one line or one number. Put the source and your name on the card, because it will be shared without the page. Use 1:1 or 4:5 for feeds, 16:9 for slides and link previews, 9:16 for stories. | More than one fact or more than one exhibit (use `story-deck` for a sequence, `executive-brief` for a page). Charts that need a legend, small labels or hovering to read, because a shared image is not interactive. An exhibit with its own `title`, because the card's headline is the title. |
| Show a sequence of steps | [annotated-timeline](https://insightcharts.dev/llms/annotated-timeline.md) | molecule | Telling how something unfolded when the events matter more than a continuous measure: a policy history, an incident, a product's milestones. Four to eight events; give a figure only to the ones where a number changed. | Events that should be read against a time scale, with gaps and overlaps to scale (use `timeline-chart`); a continuous series with a few annotated moments (use `line-chart` with `annotations`); ordered steps that are not dated (use `section` with `step`). |
| Show a sequence of steps | [hero-figure](https://insightcharts.dev/llms/hero-figure.md) | molecule | At the very top of a data story or a one-page report. The headline states the main fact with its number. The chart shows that fact. | Giving the chart its own `title` (the headline is the title; use the chart's `subtitle` for the measure). A second hero on the same page: later sections use `section` or `chart-callout`. |
| Show a sequence of steps | [proportion-statement](https://insightcharts.dev/llms/proportion-statement.md) | molecule | One proportion that is easier to read as a count of people or units than as a percentage. Round to a small whole first: 1 in 4 with icons, 37 in every 100 with a waffle. | Several shares side by side (use `bar-chart`, or `waffle-chart` with categories); a precise percentage where the decimals matter (use `big-number`); totals above 100. |
| Show a sequence of steps | [quote-figure](https://insightcharts.dev/llms/quote-figure.md) | molecule | A quotation shown next to the number it refers to: an interview finding with its survey figure, an executive's statement with the metric. One per section. | A quote with no evidence (use `pull-quote`); a figure that needs axes to read (use `chart-callout` and put the quote in prose); unattributed quotations. |
| Show a sequence of steps | [scrolly-chart](https://insightcharts.dev/llms/scrolly-chart.md) | molecule | Walking a reader through one chart in stages: show everything, highlight the subject, change the measure, add the annotation. Make ONE change per step (the highlight, the data or the encoding) so the reader can see what changed. | Steps that change several things at once, or that swap to an unrelated chart (start a new `section` instead). More than about seven steps. A fact that one view can show (use `chart-callout`). In documents that will be printed or embedded in a short frame, set `scrollMode: "steps"`. |
| Show a sequence of steps | [section](https://insightcharts.dev/llms/section.md) | molecule | The building block of a longer piece. Each section states one fact with its number in the title, explains it in a paragraph and shows it in one to three exhibits. Use `step` when the sections are read in order. | The opening of a piece (use `hero-figure`); a single chart with one callout (use `chart-callout` directly); more than three exhibits in one section (split it). |
| Show a sequence of steps | [data-explorer](https://insightcharts.dev/llms/data-explorer.md) | template | Use it when readers will want to filter the data themselves after seeing the main finding. State the finding with its number in the headline. Set `initialSelections` so the piece opens on the view the headline describes. Use the figures and the `finding` callout to give the numbers for that view. Keep to one dataset and two to four small, plain charts. Readers click the charts to filter, so keep them all the same size. | A fixed message that needs no exploration (use `executive-brief` or `visual-essay`). Charts over unrelated datasets, which cannot filter each other. More than four charts or five figures. |
| Show a sequence of steps | [explainer](https://insightcharts.dev/llms/explainer.md) | template | Use it to explain one subject to a general audience in a single narrow column. The column also works as a tall image or on a phone screen. State the main finding with its number in the headline and repeat the main number in `hook`. Make the hero exhibit the largest thing on the page. Give each numbered section one heading, one exhibit and one sentence with its main number. Write each section so it can be read without the others. Keep one accent colour on the subject (`highlight`) throughout. | Findings that need caveats and separate interpretation (use `report-page`). A chart that has to change step by step (use `visual-essay` with a scrolly block). More than five sections, because readers stop before the end. |
| Show a sequence of steps | [story-deck](https://insightcharts.dev/llms/story-deck.md) | template | Use it for a short sequence read on a phone, such as a “year in review”. Each card should be readable in a couple of seconds. State the main fact with its number on the title card. Put one fact on each later card, as a number or as one chart with one highlighted mark under a headline that states the fact. Use five to ten cards. End with a closing card and the sources. Charts in cards should have few data points and direct labels, with no legend. | Findings that need two exhibits in view at once (use `executive-brief`). A single shareable image (use `social-card`). Dense charts or long paragraphs, because a card has little room. One chart that changes step by step (use `scrolly-chart` in `steps` mode). |
| Show a sequence of steps | [timeline-story](https://insightcharts.dev/llms/timeline-story.md) | template | Use it when the reader needs the events in date order to understand a change. State the change over the whole period in the headline, with the numbers and dates. Mark the main events on the overview exhibit as annotations. Give each chapter one event. Add a small figure to a chapter only when it has a number to show. Mark the two or three most important events with `emphasis`. | Events with no measure that runs through the period (use a plain `annotated-timeline`). A comparison of two states with nothing in between (use `comparison-brief`). More than eight chapters. Merge minor events into the text of the chapter before or after. |
| Show a sequence of steps | [visual-essay](https://insightcharts.dev/llms/visual-essay.md) | template | Use it for a finding that takes several charts and some text to explain. State the main finding with its number in the headline. Put the main figure within the first screen. Alternate text and charts, with two or three short paragraphs before each exhibit. In a scrolly block change one thing per step, such as the highlight, the year or an annotation. Use one accent colour for the subject in every chart. | A summary for someone who will not scroll (use `executive-brief`). Reference material read out of order (use `report-page`). More than one or two scrolly blocks. Use one only where the chart changes between steps. |

When two forms fit, use the simpler one. When nothing fits, use a sentence with a `big-number`.

### Poster primitives

The rows above with the job "Draw a poster graphic" are the poster primitives. They are for panels of a `poster` and for the regions of the infographic templates. Each prints names and values on or beside large flat marks and has no axes by default. Use the ordinary chart for a report page and the primitive for a poster.

| The data's job | Primitive | Ordinary chart for a report page |
|---|---|---|
| Count people or things in 2 to 12 groups, in the thousands | `unit-blocks` | `pictogram-chart` |
| Compare counts of up to about 150 in 4 to 24 categories | `icon-array-grid` | `pictogram-chart` |
| Compare 2 to 8 quantities that differ by 2 to 100 times | `proportional-area` | `bar-chart` |
| State 2 to 6 related magnitudes with the number set large | `stat-circles` | `stat-row` |
| Show 5 to about 60 parts of very different sizes | `circle-pack` | `treemap` |
| Show one share at 2 to 8 dates, or 2 to 8 shares of one whole | `nested-shares` | `waffle-chart` |
| Show 1 to 6 percentages as a filled silhouette | `shape-fill` | `icon-stat` |
| Compare a short series or ranking of 3 to 12 values | `block-bar` | `bar-chart` |
| Rank 4 to about 20 named things | `pill-rank` | `bar-chart`, `ranked-list` |
| Relate two measures of the same 4 to about 15 entities | `curve-rank` | `slope-chart`, `scatter-chart` |
| Show size and changing rank of 4 to 8 entities over 4 to 10 periods | `ribbon-chart` | `bump-chart`, `area-chart` |
| Place 4 to about 20 things on one scale (depth, height, age) | `scale-ladder` | `strip-plot` |
| Place 5 to about 40 things on one scale with a magnitude as area | `bubble-scale` | `beeswarm-chart` |
| Show 4 to 12 attributes of one subject | `radial-spokes` | `bar-chart` |
| Group 6 to about 40 named things by level or period round a centre | `orbit-chart` | `comparison-table` |
| Split one total among 4 to about 14 destinations | `fan-flow` | `sankey-chart` |
| Show connections among up to about 20 ordered entities | `arc-diagram` | `sankey-chart` |
| Show which of up to about 12 things are connected, with sizes | `bubble-network` | `sankey-chart` |
| Compare 3 to about 12 entities on 2 to 5 measures with different units | `glyph-table` | `comparison-table` |

A whole poster is an infographic template (the job "Lay out a whole poster") or the `poster` molecule. See the infographics guide.

### Writing titles and text

These rules apply to every `title`, `subtitle`, deck, callout, annotation label and story step. They are hard requirements.

Write one plain statement of fact, the way a person would say it out loud, with the real numbers and the period in it.

| Write this | Not this |
|---|---|
| Monthly churn fell from 4.2% to 2.1% in 2024 | Churn halved after the March onboarding revamp, and the gain has held for six months |
| Renewables supplied 98% of Norway's electricity in 2023 | Norway runs almost entirely on renewable electricity |
| Acme had 266 active teams in December 2024, 2.4 times Globex | Acme pulled away from the pack in late 2023 |
| Solar's share rose from 2.7% to 5.5% between 2019 and 2023 | Solar is closing the gap with wind |
| Households wasted 631 million tonnes of food in 2022 | It is not a rich-country habit |

- One clause. Do not add a second half joined with a comma, "and", "but", "while", "yet", a semicolon, a colon or a dash that adds a twist, a consequence or a follow-up. If there are two facts, write two sentences or put the second in the subtitle.
- Put the number in. Write "fell from 4.2% to 2.1%", not "halved". Write "98%", not "almost entirely". Write "3 of 12", not "a handful".
- Take every number from the data. Never invent a figure, a cause or an event that the data does not show.
- No metaphor, idiom or figure of speech. Do not write "pulled away from the pack", "closing the gap", "tells the story", "the long tail" or "did the work".
- No teasing. Do not point at something the reader has to work out, such as "one hospital explains most of it" or "here is where it goes".
- No dramatic verbs (soared, plunged, surged, skyrocketed, slashed). No staged contrast ("not X, but Y").
- No rhetorical questions, no groups of three for rhythm, no sign-off lines.
- A plain label is always acceptable when there is no single fact to state: "Monthly churn, 2024".
- Subtitles name the measure, unit, population and period. Sources name the source.

### Design rules

The components enforce some of these. You are responsible for the others.

1. **State one fact in the title.** `title` is one plain statement with its number and period, or a plain label. Put the measure, unit, population and period in `subtitle`.
2. **Highlight one series.** Set `highlight` to the one or two entities the title is about. The other series are drawn in grey. Do not colour every series when the title is about one of them.
3. **Label marks directly.** Charts label line ends and bar tips where they can and show a legend only for two or more series. Do not add a legend for something that is already labelled.
4. **Use few annotations.** `annotations` mark a date, a threshold or a single value: a `line` at a target or a date, a `band` over a period, a `point` label on one value. Use two or three per chart at most.
5. **Start bars and areas at zero.** Bars and filled areas start at zero, and the components do this for you. Lines and dots may use a value axis that does not start at zero. If you rebase or use a log scale, say so in the subtitle.
6. **No dual axes, no gauges, no pie with more than 5 slices.** Two measures get two charts (or an index). A single figure is a `big-number`. Many parts become a ranked bar chart with the smallest folded into "Other" (the `top` transform does this).
7. **Change one thing per scroll step.** In a `Scrolly` story each step changes one thing: the data, the highlight or the encoding.
8. **Do not rely on tooltips.** The chart must be readable without hovering. Touch screens and exported images have no hover.
9. **Always give a source.** Pass `source`. Use `note` for method caveats, and say when data is illustrative.
10. **Give a big number context.** Add a comparison, a denominator or a period with `context`, `delta` and `deltaLabel` on `big-number`. Write "31.7%, up from 19% in 2010", not "31.7%" alone.

### How colour is assigned

You do not pick colours per series. The theme assigns them:

- Identity (which entity): the categorical palette, in stable entity order. More than 8 entities should be folded or split into small multiples.
- Emphasis: `highlight`. The first highlighted entity takes the accent colour, others take the next categorical colours, and the remaining series take the context grey.
- Magnitude and polarity: sequential and diverging ramps from the theme.
- Good or bad: `positive` and `negative`, always with a second cue such as an arrow or sign.

To change colours, change the theme (see the theming guide), not individual charts.

### Checklist

- Is the title one clause that states one fact with its number and period, or a plain label?
- Can every number in the text be found in or computed from the data?
- Is exactly one thing highlighted?
- Can it be read with no hover, at 380px wide, and in dark mode?
- Is there a `subtitle` naming the measure and a `source`?
- Would a sentence or a `big-number` show the same fact?

---

## Common chart props

Every chart built with `defineChart` accepts these on top of its own props. HTML components (big-number, callout, ...) do not. All are JSON-serialisable except the callbacks (`onSelect`, `onEvents`, `onReady`) and the function forms of `data`, `transform`, `format` and `option`. Generated from `CommonChartProps` in `packages/insightcharts/src/core/define.tsx`.

| 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 full theme, `{ light, dark }` partial tokens, or flat tokens applied to both modes. Merged over the surrounding `InsightProvider` theme. |
| `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 for this chart. Reduced-motion preferences are always respected. |
| `lazy` | `boolean` | Mount the chart only when it scrolls within 200px of the viewport. Default true (from `InsightProvider`). |
| `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: `{ click: (params, chart) => {} }`. |
| `onReady` | `(chart: EChartsInstance) => void` | Called with the ECharts instance once it is initialised. |
| `className` | `string` | Class on the figure element. |
| `style` | `CSSProperties` | Inline style on the figure element. |

---

## Data

Charts work on an array of plain row objects. The `data` prop accepts many shapes and normalises them to rows; `transform` then reshapes those rows. Both are JSON-serialisable, so a whole pipeline can live in a spec.

### Accepted `data` shapes

| Shape | Example | Notes |
|---|---|---|
| Row objects | `[{ year: 2020, value: 1 }]` | The native form. |
| Array of arrays | `[["year", "value"], [2020, 1]]` | The first array is the header. |
| Array of primitives | `[3, 5, 8]` | Becomes `{ index, value }` rows. |
| Columnar object | `{ year: [2020, 2021], value: [1, 2] }` | Every value must be an array or typed array. |
| Table object | Apache Arrow table, DuckDB result, Arquero table | Anything with `toArray()`. Rows with `toJSON()` are converted. |
| API envelope | `{ data: [...] }` | An array under `data`, `rows`, `results`, `items` or `records` is found automatically. |
| CSV text | `"year,value\n2020,1"` | Any string that is not a URL. Delimiter is detected from `,` tab `;` and the pipe character. |
| URL string | `"/data/energy.csv"` | A single-line string with no comma that starts with `http://`, `https://`, `/`, `./`, `../` or `data:`. |
| Remote source | `{ url, format, path, init, refresh }` | `format`: `csv`, `tsv`, `json`, `ndjson` (otherwise inferred from the extension, then the content type, then the content). `path`: dot path to the rows inside a JSON response, e.g. `"data.results"`. `init`: passed to `fetch`. `refresh`: re-fetch interval in ms. |
| Inline CSV | `{ csv: "...", delimiter: ";" }` | |
| Inline JSON | `{ json: anything, path: "a.b" }` | |
| Function or promise | `() => fetchRows()` or a `Promise` | Resolves to any shape above. Not JSON; client components only. |

Omit `data` on a chart inside `<InsightData>` and it reads the shared rows.

If no row array can be found, the chart shows an error telling you to pass `path`.

#### CSV type inference

CSV cells are converted: numbers (including `1,234` thousands separators), `true`/`false`, and `42%` (becomes `0.42`). Empty cells, `NA`, `N/A`, `null` and `NaN` become `null`. Values with a leading zero (`007`, zip codes) stay strings. Dates stay strings; ISO date strings (`2024-03-01`, `2024-03`) are recognised by charts as temporal. Use the `parse` transform to force a type.

#### Loading behaviour

- In-memory data resolves synchronously: no loading flash.
- URLs, functions and promises load asynchronously; the chart shows a skeleton, then the chart, or an error message with the HTTP status.
- URL loads are de-duplicated and cached for the page's lifetime, unless the source has `init` or `refresh`.
- Inline literals written in JSX are compared by content, so `data={[...]}` does not reload on every render. Arrays over 500 rows are compared by identity: keep a stable reference (a module constant or `useMemo`).

On the server, or anywhere outside React:

```ts
import { loadData, transformRows, parseCsv } from "insightcharts/data";

const rows = transformRows(await loadData({ url: "https://example.com/api", path: "data.results" }), [
  { type: "filter", field: "year", op: ">=", value: 2015 },
]);
```

### Wide and long data

Charts with `x`, `y` and `series` accept both layouts:

```tsx
// Wide: one column per series
<LineChart data={[{ year: "2022", solar: 4.6, wind: 7.3 }]} x="year" y={["solar", "wind"]} />

// Long: one row per series per x
<LineChart data={[{ year: "2022", source: "solar", share: 4.6 }, { year: "2022", source: "wind", share: 7.3 }]} x="year" y="share" series="source" />
```

In wide data the series keys are the field names (`"solar"`); in long data they are the values of the `series` field. Those keys are what `highlight` and `names` refer to.

### Transforms

`transform` takes one transform or an array applied in order. Each is a JSON object with a `type`; a function `(rows) => rows` is also accepted in JSX.

| Transform | Fields | What it does |
|---|---|---|
| `"filter"` | `field`, `op` (default `==`), `value` | Keep rows that match. |
| `"aggregate"` | `groupBy` (field or fields, optional), `measures: { name: { op, field } }` | One row per group. Omit `field` for `count`. |
| `"sort"` | `by`, `order` (`"asc"` default, or `"desc"`) | |
| `"limit"` | `n`, `offset` | Slice. |
| `"top"` | `n`, `by`, `other`, `label` | Keep the top `n` rows by `by`. To fold the rest into one row, pass both `other` (the text, e.g. `"Other"`) and `label` (the field that text goes in); the folded row's `by` value is the sum. |
| `"fold"` | `fields`, `key` (default `"key"`), `value` (default `"value"`) | Wide to long. |
| `"pivot"` | `index`, `key`, `value`, `op` (default `sum`) | Long to wide: one row per `index`, one column per distinct `key`. |
| `"bin"` | `field`, `step` or `bins`, `as` (default `<field>_bin`) | Adds the bin start as `as` and the bin end as `<as>_end`. |
| `"derive"` | `as`, `op`, `fields`, `groupBy`, `base` | Adds a computed column; see below. |
| `"rename"` | `fields: { old: "new" }` | |
| `"select"` | `fields` | Keep only these columns. |
| `"parse"` | `fields: { name: "number" \| "date" \| "string" \| "boolean" }` | Coerce types. `number` strips `,`, `$`, `%` and spaces. |

Filter ops: `==`, `!=`, `>`, `>=`, `<`, `<=`, `in` (value is an array), `not-in`, `between` (value is `[low, high]`, inclusive), `contains` (case-insensitive substring), `exists` (non-null and non-empty; pass `value: false` to invert).

Aggregate ops: `sum`, `mean`, `median`, `min`, `max`, `count`, `distinct`, `first`, `last`.

Derive ops:

- Arithmetic on two fields: `add`, `subtract`, `multiply`, `divide` (`fields: ["a", "b"]`).
- Running, on one field in row order, restarting per `groupBy` group: `percent-of-total`, `cumulative`, `rank` (1 is the largest), `change` (difference from the previous row), `percent-change`, `index` (rebased so the first row equals `base`, default 100).

#### Examples

Top five plus "Other":

```json
[
  { "type": "aggregate", "groupBy": "category", "measures": { "revenue": { "op": "sum", "field": "amount" } } },
  { "type": "top", "n": 5, "by": "revenue", "other": "Other", "label": "category" }
]
```

Index several series to 100 at the start so growth is comparable (say "Indexed, 2019 = 100" in the subtitle):

```json
{ "type": "derive", "as": "indexed", "op": "index", "fields": ["value"], "groupBy": "country" }
```

Wide to long:

```json
{ "type": "fold", "fields": ["solar", "wind"], "key": "source", "value": "share" }
```

### Order of operations

Standalone chart: load `data`, then the chart's `transform`.

Inside `<InsightData>`: load the shared `data`, apply the store's `transform`, filter by the other charts' selections, then apply the chart's own `transform`.

---

## Theming and dark mode

### The default theme

With no configuration, charts inherit the page font and read shadcn/ui's `--background`, `--foreground` and `--muted-foreground` variables when they exist, with neutral fallbacks when they do not. The series colours are InsightCharts' own palette, whose order is chosen so neighbouring colours stay distinguishable under colour-vision deficiency. Keep the order if you re-skin.

### Three ways to theme

#### 1. CSS variables

Every colour token of the default theme reads an `--ic-*` variable first. Set them in your stylesheet, globally or on any ancestor:

```css
:root {
  --ic-accent: #7c3aed;
  --ic-series-1: #7c3aed;
  --ic-font-display: "Fraunces", serif;
}
.dark {
  --ic-accent: #a78bfa;
  --ic-series-1: #a78bfa;
}
```

`npx shadcn@latest add @insightcharts/theme` writes the full set with their default values into your global CSS so you can edit them in place.

| CSS variable | Token | Light default | Dark default |
|---|---|---|---|
| `--ic-surface` | `surface` | `var(--background, #fcfcfb)` | `var(--background, #1a1a19)` |
| `--ic-ink` | `ink` | `var(--foreground, #0b0b0b)` | `var(--foreground, #f0efec)` |
| `--ic-ink-secondary` | `inkSecondary` | `#52514e` | `#c3c2b7` |
| `--ic-muted` | `muted` | `var(--muted-foreground, #898781)` | `var(--muted-foreground, #898781)` |
| `--ic-grid` | `grid` | `#e1e0d9` | `#2c2c2a` |
| `--ic-axis` | `axis` | `#c3c2b7` | `#383835` |
| `--ic-accent` | `accent` | `#2a78d6` | `#3987e5` |
| `--ic-context` | `context` | `#c3c2b7` | `#52514e` |
| `--ic-positive` | `positive` | `#0ca30c` | `#0ca30c` |
| `--ic-negative` | `negative` | `#d03b3b` | `#e66767` |
| `--ic-series-1` | `categorical[0]` | `#2a78d6` | `#3987e5` |
| `--ic-series-2` | `categorical[1]` | `#eb6834` | `#d95926` |
| `--ic-series-3` | `categorical[2]` | `#1baf7a` | `#199e70` |
| `--ic-series-4` | `categorical[3]` | `#eda100` | `#c98500` |
| `--ic-series-5` | `categorical[4]` | `#e87ba4` | `#d55181` |
| `--ic-series-6` | `categorical[5]` | `#008300` | `#0ca30c` |
| `--ic-series-7` | `categorical[6]` | `#6250d6` | `#9085e9` |
| `--ic-series-8` | `categorical[7]` | `#e34948` | `#e66767` |
| `--ic-font` | `fontFamily` | `inherit` | `inherit` |
| `--ic-font-display` | `displayFamily` | `var(--ic-font, inherit)` | `var(--ic-font, inherit)` |

The `sequential` and `diverging` ramps, `fontSize`, `radius` and `lineWidth` have no CSS variable; set them with the `theme` prop.

#### 2. The `theme` prop

On any chart, on `InsightProvider`, or on HTML components that declare it. It accepts:

- flat tokens, applied to both modes: `theme={{ accent: "#7c3aed", radius: 2 }}`
- per-mode tokens: `theme={{ light: { accent: "#7c3aed" }, dark: { accent: "#a78bfa" } }}`
- a full theme object from `createTheme(input, base?)`

A chart's `theme` is merged over the surrounding provider's. Token values may be literals or CSS variable references (`"var(--brand, #2a78d6)"`); they are resolved against the chart's own DOM node, so scoped overrides work.

Tokens: `surface`, `ink`, `inkSecondary`, `muted`, `grid`, `axis`, `accent`, `context`, `positive`, `negative`, `categorical[]`, `sequential[]`, `diverging[]`, `fontFamily`, `displayFamily`, `fontSize`, `radius`, `lineWidth`.

#### 3. The shadcn preset

```tsx
import { InsightProvider } from "insightcharts";
import { shadcnTheme } from "insightcharts/themes";

<InsightProvider theme={shadcnTheme}>{children}</InsightProvider>
```

`shadcnTheme` takes series colours from `--chart-1` to `--chart-5`, the accent from `--chart-1` (falling back to `--primary`) and gridlines from `--border`. shadcn's stock chart colours are not ordered for colour-vision-deficiency separation, so keep direct labels or legends on. `insightcharts/themes` also exports `defaultTheme`, `createTheme`, six presets and the `themes` record that holds all of them by name.

### Presets

`editorialTheme`, `ledgerTheme`, `monoTheme`, `earthTheme`, `scienceTheme` and `posterTheme` each define a light and a dark token set, with categorical palettes checked for colour-vision-deficiency separation in both modes. Unlike `insight` and `shadcn`, which follow the host page, a preset paints for its own surface: put it in a container with the matching background, which `themeSurfaces[name]` gives you as `{ light, dark }`.

```tsx
import { InsightProvider } from "insightcharts";
import { editorialTheme, themeSurfaces } from "insightcharts/themes";

<div style={{ background: themeSurfaces.editorial.light, padding: 24 }}>
  <InsightProvider theme={editorialTheme} mode="light">{children}</InsightProvider>
</div>
```

### Dark mode

`mode` is a prop on every chart and on `InsightProvider`:

- `"auto"` (default): match what the page looks like. In order: the nearest ancestor with a `.dark` / `.light` class or a `data-theme`, `data-mode`, `data-color-mode` or `data-color-scheme` attribute; otherwise the luminance of the nearest painted background; otherwise the page's `color-scheme` and the OS preference.
- `"system"`: follow the OS preference.
- `"light"` / `"dark"`: force it.

Charts re-resolve their colours when the root's class or theme attributes change, so toggles such as next-themes work without a remount. Each component root carries `data-ic-mode="light|dark"`.

### Restyling the chrome

The title, subtitle, legend and source line are HTML elements, each with a `data-slot` attribute: `ic-figure`, `ic-header`, `ic-title`, `ic-subtitle`, `ic-legend`, `ic-plot`, `ic-source`, `ic-table`, `ic-actions`, `ic-menu`, `ic-skeleton`, `ic-state`. HTML components add their own (for example `ic-big-number-value`). Target them from CSS:

```css
[data-slot="ic-title"] { font-size: 1.5rem; }
```

`className` and `style` on a chart apply to its `figure` element.

---

## Crossfiltering with InsightData

`InsightData` loads data once and shares it. Charts inside it that do not pass their own `data` read the shared rows, and any chart with `select` filters all the others when the reader clicks a mark.

```tsx
"use client";
import { BarChart, InsightData, LineChart } from "insightcharts";

export function Sales({ rows }: { rows: Record<string, unknown>[] }) {
  return (
    <InsightData data={rows}>
      <BarChart
        id="by-region"
        select
        transform={{ type: "aggregate", groupBy: "region", measures: { revenue: { op: "sum", field: "revenue" } } }}
        x="region"
        y="revenue"
        title="Revenue by region"
      />
      <LineChart
        transform={{ type: "aggregate", groupBy: "month", measures: { revenue: { op: "sum", field: "revenue" } } }}
        x="month"
        y="revenue"
        title="Revenue by month"
        subtitle="Click a region above to filter"
      />
    </InsightData>
  );
}
```

### How it behaves

- `select` makes marks clickable. `select={true}` uses the chart's own category field (for `bar-chart` that is `x`; for `line-chart` it is `series`). `select="field"` names the field explicitly.
- A click toggles that value in the chart's selection; several values can be selected. A click on empty plot area clears it.
- A selection filters every other chart, never the chart that made it. The selecting chart keeps its full domain and fades the unselected marks.
- Each chart's own `transform` runs after the shared filter, so charts can aggregate the filtered rows differently.
- A chart that passes its own `data` inside `InsightData` is not filtered, but its selection still filters the others.
- Without an `InsightData` ancestor, `select` still works locally: the chart fades unselected marks and calls `onSelect`.

### Props

`InsightData`:

| Prop | Type | Description |
|---|---|---|
| `data` | `DataInput` | Shared data, any accepted shape. |
| `transform` | `Transform \| Transform[]` | Applied once to the shared rows, before filtering. |
| `selections` | `Record<string, Selection>` | Controlled selections, keyed by chart id. |
| `onSelectionsChange` | `(selections) => void` | Called on every change. |

On charts: `select`, `onSelect(values, field)`, and `id` (a stable key for the chart's selection; set it when you control or persist selections, otherwise a generated id is used).

A `Selection` is `{ field, values?: string[], range?: [min, max] }`. Clicks produce `values`; `range` can be set programmatically and filters with an inclusive between.

### Reading or driving the store

```tsx
import { useInsightData } from "insightcharts";

function ClearFilters() {
  const store = useInsightData(); // null outside <InsightData>
  if (!store || Object.keys(store.selections).length === 0) return null;
  return <button onClick={() => store.clear()}>Clear filters</button>;
}
```

The store exposes `all` (unfiltered rows), `rows`, `status`, `error`, `selections`, `select(owner, selection | null)`, `clear()` and `rowsFor(owner?)` (rows filtered by every selection except `owner`'s).

### Linked tooltips

Separately from filtering, charts that share a `group` id link their tooltips and axis pointers: `group="sales"` on each.

### Design notes

- Tell the reader the charts are linked, with a subtitle such as "Click a bar to filter".
- The charts must show their main fact before the reader clicks anything.

---

## Scroll and swipe stories with Scrolly

`Scrolly` pins a graphic and changes its state as the reader moves through a list of steps. Because the same chart receives new props at each step, ECharts animates between the states.

```tsx
"use client";
import { LineChart, Scrolly } from "insightcharts";

const data = [
  { year: "2019", solar: 2.7, wind: 5.3 },
  { year: "2021", solar: 3.7, wind: 6.5 },
  { year: "2023", solar: 5.5, wind: 7.8 },
];

const steps = [
  { id: "both", content: "Solar and wind share of global electricity generation, 2019 to 2023.", highlight: [] as string[] },
  { id: "wind", content: "Wind's share rose from 5.3% in 2019 to 7.8% in 2023.", highlight: ["wind"] },
  { id: "solar", content: "Solar's share rose from 2.7% in 2019 to 5.5% in 2023.", highlight: ["solar"] },
];

export function EnergyStory() {
  return (
    <Scrolly steps={steps}>
      {({ step }) => (
        <LineChart
          data={data}
          x="year"
          y={["solar", "wind"]}
          format="{value}%"
          highlight={step.highlight}
          title="Solar and wind share of electricity, 2019 to 2023"
          subtitle="Share of global electricity generation"
          source="Ember"
        />
      )}
    </Scrolly>
  );
}
```

### Steps and state

Each step is `{ id?, content, ...yourKeys }`. `content` is the text for the step (a sentence or two). Any other keys are yours: the state the graphic should be in. `id` is also set as the step element's `id`, so it works as a link anchor.

`children` is a function that receives `{ index, step, progress, count }` and returns the graphic. `progress` runs 0 to 1 through the active step in scroll mode and is 0 in the other modes.

`children` is a function, so `Scrolly` must be used from a client component.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `steps` | `StoryStep[]` | | The steps. |
| `children` | `(state) => ReactNode` | | Renders the graphic for the active step. |
| `mode` | `"auto" \| "scroll" \| "swipe" \| "steps"` | `"auto"` | See below. |
| `side` | `"left" \| "right"` | `"left"` | Which side the text column sits on in scroll mode. |
| `stickyTop` | `number \| string` | `0` | Offset from the top of the viewport at which the graphic pins; set it to the height of a fixed header. |
| `stepHeight` | `string` | `"80vh"` | Scroll distance per step. |
| `index` | `number` | | Controlled active step. |
| `onStepChange` | `(index, step) => void` | | Called when the active step changes. |
| `theme` | `ThemeInput` | | Theme for the step cards. |
| `colorMode` | `"auto" \| "system" \| "light" \| "dark"` | provider's | Colour mode for the step cards. Named `colorMode` because `mode` is the interaction mode. |
| `className`, `style` | | | On the root element. |

### Modes

- `"scroll"`: the graphic is sticky and the steps scroll past; the step crossing the middle of the viewport is active. When the container is narrower than 768px the steps overlay the graphic as cards instead of sitting beside it.
- `"swipe"`: the graphic sits on top and the steps are cards that swipe horizontally, with Previous and Next buttons.
- `"steps"`: one card at a time with Previous and Next buttons. No scroll hijacking; suitable for embeds.
- `"auto"`: swipe when the container is under 640px wide on a coarse-pointer (touch) device, scroll otherwise.

In swipe and steps modes the left and right arrow keys move between steps. In scroll and swipe modes all step text is in the document.

### Writing steps

- Change one thing per step: the data, the highlight or the encoding.
- Keep the same chart component in the same position across steps and change its props. Swapping to a different component, or changing its `key`, remounts it and loses the transition.
- Use three to seven steps. Each step is one or two plain sentences.
- Each step states one fact about what the chart shows at that step, with the number from the data: "Solar's share rose from 2.7% in 2019 to 5.5% in 2023." Do not start a step with "But" or "And" to link it to the previous one.
- The first step shows all of the data with no highlight.
- Give the chart a `title` that is true at every step (a plain label works), or set the title per step from the step's keys.
- Step text follows the same writing rules as titles. See "Choosing a form".

---

## Infographics

An infographic is a template with `category: "infographic"`. It draws one designed sheet, called a poster: a painted background, a large title, little other text, and one large graphic or several graphics laid out together. Every infographic is composed on the `poster` molecule from atoms with `category: "poster"`, called poster primitives.

### When to choose a poster

| The piece is | Use |
|---|---|
| One image that is read in a few seconds and shared as a picture | An infographic template |
| One image with a layout no infographic template has | The `poster` molecule with your own panels |
| One fact at a fixed social size (1:1, 4:5, 16:9, 9:16) | `social-card` |
| A page with paragraphs, a method note, recommendations or charts with axes | A report-style template such as `executive-brief`, `report-page` or `visual-essay` |
| A dashboard the reader filters | `data-explorer` |

A poster suits large counts, rankings, shares, flows and scales that read from the size of the marks. It does not suit dense time series or anything that needs axes and gridlines to be read.

### The infographic templates

Pick the template from the decision table in "Choosing a form" (rows with the job "Lay out a whole poster"). Each template's page lists its regions and has a complete example.

### Writing an infographic spec

```json
{
  "type": "count-poster",
  "theme": "noir",
  "kicker": "Education",
  "title": "Norland's schools taught 1.84 million pupils in 2025",
  "subtitle": "Pupils enrolled in state schools by stage, autumn term 2025.",
  "unit": 1000,
  "unitLabel": "1,000 people",
  "hero": {
    "data": [
      { "stage": "Primary", "pupils": 820000 },
      { "stage": "Lower secondary", "pupils": 480000 },
      { "stage": "Upper secondary", "pupils": 390000 },
      { "stage": "Vocational", "pupils": 170000 }
    ],
    "name": "stage",
    "value": "pupils",
    "title": "820,000 pupils were in primary school"
  },
  "sources": "Norland Ministry of Education, school census 2025",
  "note": "Norland is an invented country. All figures are illustrative."
}
```

Render it with `<Insight spec={spec} />`.

- `title` is required. It is the poster's one fact, as a plain sentence with its number. `kicker` is a short topic label and `subtitle` names the measure, population and period.
- `theme` is a poster theme name. Each template has its own default.
- Each template has named region props (`hero`, `reference`, `area`, `bars` and `shares` on `count-poster`; `scale`, `figures` and `side` on `scale-poster`). Read the template's page for its regions.
- A region takes a compact config: `data` rows, the field names, and any other prop of the primitive that draws the region. A `title`, `subtitle`, `source` or `note` in the config becomes the heading and source line of that panel.
- A region also takes a full spec with its own `type`. That replaces the primitive the template would have drawn.
- `sources`, `note` and `credit` are the footer. Always set `sources`. Say in `note` when data is illustrative.
- `linked: true` makes marks clickable. A click highlights the same name in every other graphic that has it and filters graphics that read the shared `data` prop.
- `download: true` adds a "Download PNG" control under the poster.
- `maxWidth` limits the width. `mode` is `"light"` by default and a poster does not follow the page's colour mode.

Keep names identical across regions (the same spelling of each entity) so `linked` can join them.

### Composing a poster with the poster frame

Use `poster` when no template has the layout.

```json
{
  "type": "poster",
  "theme": "forest",
  "kicker": "Transport",
  "title": "Tarn Valley buses carried 9.6 million passengers in 2025",
  "subtitle": "Passengers on the valley's seven bus routes, January to December 2025.",
  "panels": [
    { "span": 5, "valign": "center", "content": { "type": "big-number", "size": "hero", "value": "9.6 million", "label": "Passengers in 2025", "context": "8.9 million in 2024" } },
    {
      "span": 7,
      "title": "Route 4 carried 2.3 million passengers",
      "subtitle": "Passengers by route, thousands, 2025",
      "content": { "type": "pill-rank", "data": [{ "route": "Route 4", "k": 2300 }, { "route": "Route 1", "k": 1900 }, { "route": "Route 7", "k": 1500 }], "name": "route", "value": "k", "format": "{value}k", "highlight": "Route 4" }
    },
    {
      "title": "Passenger numbers were 6.1 million in 2021",
      "content": { "type": "block-bar", "data": [{ "year": "2021", "m": 6.1 }, { "year": "2023", "m": 8.2 }, { "year": "2025", "m": 9.6 }], "name": "year", "value": "m", "format": "{value}m" }
    }
  ],
  "sources": "Tarn Valley Transport Authority",
  "note": "Tarn Valley is an invented place. All figures are illustrative."
}
```

- `panels` is required. Each panel is `{ content, title?, subtitle?, span?, rowSpan?, source?, note?, align?, valign?, bleed?, id? }`.
- `content` is a component spec. Put the panel's heading in the panel's `title`, not in the chart's `title`. Every panel heading is then set in the same type.
- `columns` is 12 by default. `span` is in those units and defaults to the full width. `span: 5` beside `span: 7` makes one row. `columns: 2` or `columns: 3` gives a simple grid.
- `aspect` fixes the shape (`"4:5"`, `"16:9"`, `0.75`). The poster still grows when its content needs more height.
- `rules` is `"dotted"` (default), `"solid"` or `"none"`.
- The frame passes its theme and colour mode to everything inside. Do not set `theme` or `mode` on a chart in a panel.
- Use at most about six panels. Give charts in panels a `height` when they do not size themselves (`bar-chart`, `donut-chart`, `treemap`). Poster primitives size themselves.

### Poster themes

Eight themes, passed by name as `theme`.

| Name | Ground | Marks |
|---|---|---|
| `noir` | Near-black `#0d0d0f` | Yellow, sky blue, coral, off-white, green. White type. |
| `magenta` | Magenta `#c2006b` | Pale pink, near-black, cyan, yellow. White type. |
| `dusk` | Violet gradient, `#24104f` to `#5e2067` | Orange, pale yellow, pink, lilac, mint. White type. |
| `paper` | Off-white `#f3ecdf` | Red, ink black, warm grey, blue. Black type. `mode: "dark"` gives the same design on charcoal `#1d1b18`. |
| `ocean` | Navy to teal gradient, `#041c3a` to `#084c5c` | Aqua, coral, sand, blue. White type. |
| `forest` | Dark green `#0f3d2a` | Lime, orange, cream, light blue. Cream type. |
| `blueprint` | Cobalt `#1447c8` | Yellow, white, salmon, pale blue. White type. Monospace display face. |
| `sunrise` | Cream to peach gradient, `#fff1e0` to `#ffdfc6` | Plum, tangerine, teal, blue. Plum type. |

- Seven themes have one look: the same tokens in light and dark. Only `paper` has a different dark variant.
- A poster theme has 4 or 5 categorical colours. Fold further entities into "Other" or shade by value.
- `posterThemes` and `posterBackgrounds` are exported from `insightcharts/themes`. `posterBackgrounds[name].light` is the CSS background, which is a gradient for `dusk`, `ocean` and `sunrise`.
- Do not hard-code colours in a spec. Pick a theme.

### Poster primitives

The data job to primitive table is in "Choosing a form" under "Poster primitives". A primitive is a chart built with `defineChart` and accepts the common chart props (`data`, `transform`, `title`, `highlight`, `format`, `select`, ...). It prints names and values on or beside its marks, has no axes by default and sets its own height. It works in any theme and outside a poster.

Any other atom also fits a panel. `big-number` (with `size: "hero"`), `pictogram-chart`, `treemap`, `waffle-chart`, `segmented-bar`, `donut-chart`, `bar-chart` and `icon-stat` are used in the `poster` examples.

### Icons

An icon prop (`icon`, `icons`, `iconField` values) takes a built-in name or a custom single path written as `"path://M0 0..."` on a 24 by 24 grid. Use only these names:

- People: `person`, `woman`, `child`, `baby`, `group`
- Home and buildings: `house`, `building`, `factory`, `hospital`, `school`, `shop`
- Transport: `car`, `bus`, `train`, `bike`, `plane`, `ship`, `truck`, `rocket`
- Nature and energy: `tree`, `leaf`, `sun`, `cloud`, `rain`, `drop`, `snow`, `wind-turbine`, `solar-panel`, `flame`, `bolt`, `battery`, `barrel`, `plug`, `mountain`, `wave`, `globe`
- Food and farming: `wheat`, `bread`, `apple`, `carrot`, `fish`, `cow`, `chicken`, `milk-bottle`, `cup`, `bottle`, `fork-knife`
- Money and shopping: `coin`, `banknote`, `cart`, `bag`, `bin`
- Objects: `phone`, `laptop`, `book`, `lightbulb`, `heart`, `cross`, `pill`, `syringe`, `clock`, `calendar`, `flag`, `star`, `pin`, `lock`, `satellite`
- Shapes: `circle`, `square`

An unknown name falls back to another icon without an error. Check every icon name against this list. `icons`, `iconNames`, `iconGroups`, `resolveIcon` and `iconSymbol` are exported from `insightcharts` and `insightcharts/core`. The `Icon` component draws one icon as inline SVG and takes `name`, `size`, `color`, `title` and `fallback`.

### PNG download

- `download: true` on `poster` or on any infographic adds a "Download PNG" control under the sheet. The image is the whole sheet without the control.
- On `poster`, `exportWidth` sets the image width (default 2400), `filename` the file name (default: a slug of the title), `downloadLabel` the label and `onExport` receives the `Blob`. The infographic templates take `download` only.
- With `download` set, every chart in the poster mounts at once instead of lazily.
- From code: `rasterize(element, pixelWidth)` and `canvasToBlob(canvas)` from `insightcharts/core` paint any element to a PNG, and `downloadBlob(blob, name)` saves it. The poster sheet is the element with `data-slot="ic-poster"`.
- The painter draws backgrounds including linear and radial gradients, borders, radii, clipping, text, inline SVG and canvases. It does not draw outer or blurred shadows, CSS transforms, conic or repeating gradients or `url()` backgrounds.

### Phone layout

A poster lays out from its own width, not the viewport.

| Poster width | Layout |
|---|---|
| 760px and wider | The grid as written. |
| 600 to 759px | Two columns. On a 12-unit grid a panel with `span` up to 6 takes one column and a wider panel takes both. |
| Under 600px | One column, every panel full width, in the order of `panels`. |

Under 600px the padding is 20px, the gap is 28px and a fixed `aspect` is dropped. Order `panels` so the poster reads correctly as one column. Poster primitives lay themselves out again for the narrow width.

### Checklist

- The `title` is one clause with its number and period.
- Every panel heading is one fact about that panel or a plain label.
- `sources` is set.
- Every icon name is in the list above.
- Entity names are spelt the same in every region.
- There are at most about six panels.
- No chart in a panel sets its own `theme` or `mode`.

---

## Export

### The export menu

```tsx
<BarChart data={data} x="country" y="share" title="Renewable share of electricity by country" exportable />
```

`exportable` adds an "Export" menu at the top right of the figure (visible on hover or keyboard focus). `true` offers PNG, SVG, PDF and CSV. Pass a list to choose from all six formats: `exportable={["png", "jpeg", "svg", "pdf", "csv", "json"]}`. Set it once for every chart with `<InsightProvider exportable>`.

### Formats

| Format | Contents |
|---|---|
| `png`, `jpeg` | The chart re-rendered off-screen at `pixelRatio` (default 2), with the title, subtitle and source line drawn in, on the theme's surface colour. |
| `svg` | A standalone SVG with the same chrome as text elements. |
| `pdf` | A single page containing the image. |
| `csv`, `json` | The rows the chart drew, after loading, crossfilter and `transform`. |

Image exports use the chart's current size, theme and colour mode, and never have a transparent background unless you pass one.

### Programmatic export

Every chart forwards a ref with `export(options)`, `getInstance()` and `getOption()`.

```tsx
"use client";
import { useRef } from "react";
import { LineChart } from "insightcharts";
import type { ChartHandle } from "insightcharts";

export function Downloadable({ data }: { data: Record<string, unknown>[] }) {
  const chart = useRef<ChartHandle>(null);
  return (
    <>
      <LineChart ref={chart} data={data} x="year" y="solar" title="Solar generation by year" />
      <button onClick={() => chart.current?.export({ format: "png", filename: "solar" })}>Download PNG</button>
    </>
  );
}
```

Options:

| Option | Default | Description |
|---|---|---|
| `format` | `"png"` | `png`, `jpeg`, `svg`, `pdf`, `csv` or `json`. |
| `filename` | slug of the title | Without extension. |
| `pixelRatio` | `2` | Raster scale. |
| `chrome` | `true` | Include the title, subtitle and source line in image exports. |
| `background` | theme surface | Background colour. |
| `download` | `true` | Set false to get the `Blob` back without triggering a download. |

`export()` always resolves to the `Blob`. Export runs in the browser; there is no server-side image rendering in the package.

### The data table

`table` adds a collapsible "View data" table under the chart with the same rows. Screen-reader users and readers who need exact values can use it.

Lower-level functions (`exportChart`, `toSvgString`, `toCanvas`, `downloadBlob`) are exported from `insightcharts/core` for custom charts built on `Chart`.

---

## The JSON spec

A spec is a component described as plain JSON: `type` is the component's kebab-case name, every other key is a prop.

```json
{
  "type": "line-chart",
  "data": { "url": "/data/energy.csv" },
  "transform": [{ "type": "filter", "field": "year", "op": ">=", "value": 2015 }],
  "x": "year",
  "y": ["solar", "wind"],
  "highlight": "solar",
  "annotations": [{ "type": "line", "axis": "x", "value": "2020", "label": "Pandemic" }],
  "title": "Solar and wind share of electricity since 2015",
  "subtitle": "Share of global electricity generation, %",
  "source": "Ember"
}
```

```tsx
import { Insight } from "insightcharts";

<Insight spec={spec} />
```

### When to use a spec

- The chart is chosen at runtime: by an AI agent, a CMS field, an API response.
- You need to store, diff or validate charts as data.

When you are writing a page by hand, JSX with named imports is the better choice: it is type-checked and only bundles what you import (the package ships one module per component). Rendering `Insight` registers, and therefore bundles, every component.

### Rules

- `type` must be a component name from the manifest. An unknown type renders a visible message listing the available types; it does not throw.
- Props are the same as in JSX. Field names are strings in both.
- Specs nest. Wherever a molecule or template takes content (a slot), it accepts text or another spec.
- Everything is expressible except functions: no callbacks (`onSelect`, `onEvents`, `onReady`), and no function forms of `data`, `transform`, `format` or `option`. Use the string and object forms: URLs and `{ url, path }` for data, transform objects, format strings such as `"percent"` or `"{value} kg"`, and an `option` object for ECharts overrides.

### Validate before rendering

The schema is generated from the component metadata:

- `https://insightcharts.dev/schema/insight-spec.json`

It is a `oneOf` over component types. Each type lists the component's own props (plus the common chart props for charts, or `className`, `style`, `theme` and `mode` for HTML components) and rejects unknown keys, which catches misspelt and invented props. Use any JSON Schema (draft-07) validator. The component manifest, with every component's description, props and example, is at `https://insightcharts.dev/schema/manifest.json` and ships in the package as `insightcharts/manifest.json`.

### Formats and annotations in JSON

`format`: `"auto"`, `"compact"` (12.9K), `"percent"` (0.42 becomes 42%), `"percent-raw"` (42 becomes 42%), `"integer"`, `"signed"`, `"year"`, `"currency:USD"`, `"decimal:2"`, a template containing `{value}` such as `"{value} kg"`, or an `Intl.NumberFormat` options object.

`annotations` (cartesian charts), positioned in data coordinates:

```json
[
  { "type": "line", "axis": "y", "value": 50, "label": "Target", "dashed": true },
  { "type": "band", "axis": "x", "from": "2020", "to": "2021", "label": "Lockdowns" },
  { "type": "point", "x": "2023", "y": 5.5, "label": "5.5% in 2023", "position": "top" }
]
```

`line` also takes `emphasis` (draw in ink rather than muted). `point` takes `dot: false` to hide the marker; its `label` supports `\n` line breaks.

### Registering your own components

`Insight` and nested slots look components up by `meta.name`. To make a spec resolve to your own component, or to a registry copy you have customised, register it:

```tsx
import { registerComponents } from "insightcharts";
import { BarChart } from "@/components/insightcharts/atoms/bar-chart";

registerComponents({ BarChart }); // the last registration for a name wins
```

`listComponents()` returns the metadata of everything registered, and `getComponent(type)` returns one component.

---

## Recipes

Each recipe uses `bar-chart`, `line-chart` and `big-number`, which are the reference components. Check the component catalogue for more specific forms before settling on these.

Where a recipe shows its rows, the title states a fact from those rows. Where the rows are not shown (`data={rows}`), the title is a plain label. When you have the data, replace the label with one fact and its number, following the writing rules in "Choosing a form".

### Ranked bars with one highlighted

```tsx
const rows = [
  { country: "Norway", share: 98 },
  { country: "Brazil", share: 89 },
  { country: "Canada", share: 68 },
  { country: "Germany", share: 52 },
];

<BarChart
  data={rows}
  x="country"
  y="share"
  format="{value}%"
  highlight="Brazil"
  title="Renewables supplied 89% of Brazil's electricity in 2023"
  subtitle="Share of electricity from renewables, 2023"
  source="Ember"
/>
```

A single-series bar chart sorts descending and labels each bar, so there is no value axis to read. `highlight` takes the category label.

### Top five plus Other

```tsx
<BarChart
  data={orders}
  transform={[
    { type: "aggregate", groupBy: "category", measures: { revenue: { op: "sum", field: "amount" } } },
    { type: "top", n: 5, by: "revenue", other: "Other", label: "category" },
  ]}
  x="category"
  y="revenue"
  format="currency:USD"
  title="Revenue by category"
/>
```

### Highlight one line among several

```tsx
<LineChart
  data={long}
  x="year"
  y="share"
  series="country"
  highlight="Denmark"
  format="percent"
  title="Wind share of electricity by country"
  subtitle="Wind as a share of electricity generation"
  source="Ember"
/>
```

Long data: one row per country per year. Every country other than Denmark is drawn in the context grey.

### Annotate a date, a period and a value

```tsx
<LineChart
  data={monthly}
  x="month"
  y="signups"
  annotations={[
    { type: "line", axis: "x", value: "2024-03", label: "Pricing change" },
    { type: "band", axis: "x", from: "2024-07", to: "2024-08", label: "Outage" },
    { type: "point", x: "2024-11", y: 4210, label: "4,210 in November" },
  ]}
  title="Signups reached 4,210 in November 2024"
  subtitle="New accounts per month, 2024"
  source="Internal analytics"
/>
```

Annotation `value`, `from`, `to` and `x` must match the x values in the data.

### Compare growth with an index

```tsx
<LineChart
  data={long}
  transform={{ type: "derive", as: "indexed", op: "index", fields: ["value"], groupBy: "country" }}
  x="year"
  y="indexed"
  series="country"
  title="GDP by country since 2019"
  subtitle="GDP index, 2019 = 100"
/>
```

The rebasing must be stated in the subtitle. Rows must already be in time order within each group.

### A big number with context

```tsx
<BigNumber
  value={0.317}
  format="percent"
  label="Share of global electricity from renewables"
  delta={0.021}
  deltaLabel="vs 2023"
  context="Up from 19% in 2010"
  size="hero"
/>
```

Numeric `delta` values are fractions rendered as signed percentages (`0.021` is +2.1%). Pass `upIsGood={false}` when an increase is bad.

### Stat row above a chart

Until a molecule covers your case, compose atoms with ordinary layout. Use container-friendly CSS (`minmax(0, 1fr)`, `minWidth: 0`) so charts can shrink.

```tsx
<section style={{ display: "grid", gap: "2rem" }}>
  <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(160px, 1fr))", gap: "1.5rem" }}>
    <BigNumber value={1240000} format="compact" label="Active users" delta={0.12} deltaLabel="vs last quarter" />
    <BigNumber value={0.043} format="percent" label="Monthly churn" delta={-0.008} deltaLabel="vs last quarter" upIsGood={false} />
    <BigNumber value={38} format="{value} min" label="Median session" context="Also 38 min in January" />
  </div>
  <LineChart data={weekly} x="week" y="active" title="Weekly active users" source="Product analytics" />
</section>
```

### Load from an API on the server

```tsx
import { loadData } from "insightcharts/data";
import { BarChart } from "insightcharts";

export default async function Page() {
  const rows = await loadData({ url: "https://api.example.com/v1/emissions", path: "data.results" });
  return <BarChart data={rows} x="sector" y="mt_co2" format="{value} Mt" title="CO2 emissions by sector" source="Example API" />;
}
```

In a client-only app, pass the same `{ url, path }` object straight to `data`. The chart shows a skeleton while it loads.

### A JSON spec

```json
{
  "type": "bar-chart",
  "data": [
    { "country": "Norway", "share": 98 },
    { "country": "Brazil", "share": 89 },
    { "country": "Canada", "share": 68 }
  ],
  "x": "country",
  "y": "share",
  "format": "{value}%",
  "highlight": "Norway",
  "title": "Renewables supplied 98% of Norway's electricity in 2023",
  "subtitle": "Share of electricity generation from renewables, 2023",
  "source": "Ember"
}
```

Render with `<Insight spec={spec} />` and validate against `https://insightcharts.dev/schema/insight-spec.json`. `data` can also be a URL with a `transform`:

```json
{
  "type": "bar-chart",
  "data": { "url": "/data/renewables.csv" },
  "transform": [{ "type": "filter", "field": "year", "op": "==", "value": 2023 }],
  "x": "country",
  "y": "share",
  "title": "Renewable share of electricity by country, 2023"
}
```

### Override one ECharts setting

```tsx
<LineChart data={rows} x="date" y="price" option={{ yAxis: { min: 0, max: 200 } }} title="Daily price" />
```

`option` is deep-merged over what the component generates. Use a prop when one exists, and `option` only when none does.

---

## Arc diagram (`arc-diagram`)

> Places entities in order on a line and joins each related pair with a semicircular arc whose thickness is the value of the connection; dots are sized by each entity's total.

- Component: `ArcDiagram` (import from `insightcharts`)
- Spec type: `"arc-diagram"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Connections among up to about 20 entities that have a meaningful order (stops on a line, chapters, age groups, teams by size): trips between stations, trade between neighbours, characters sharing scenes.

### Avoid

Flows with a direction through stages (use sankey-chart); one source splitting into parts (use fan-flow); a full matrix of every pair where exact values matter (use heatmap); more than about 20 entities or 60 connections (use heatmap).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/arc-diagram
```

The file lands at `components/insightcharts/atoms/arc-diagram.tsx`. `@insightcharts/arc-diagram-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ArcDiagram } from "insightcharts";

const data = [
  { a: "Harbour", b: "Market", trips: 4200 },
  { a: "Harbour", b: "Quay", trips: 900 },
  { a: "Quay", b: "Market", trips: 1300 },
  { a: "Market", b: "Town Hall", trips: 2600 },
  { a: "Market", b: "University", trips: 3100 },
  { a: "Town Hall", b: "University", trips: 1500 },
  { a: "Town Hall", b: "Hospital", trips: 1100 },
  { a: "University", b: "Park", trips: 800 },
  { a: "University", b: "Airport", trips: 1900 },
  { a: "Park", b: "Hospital", trips: 600 },
  { a: "Hospital", b: "Stadium", trips: 700 },
  { a: "Stadium", b: "Airport", trips: 1200 },
  { a: "Harbour", b: "Airport", trips: 2300 },
  { a: "Market", b: "Stadium", trips: 1700 },
  { a: "Quay", b: "University", trips: 500 },
];

<ArcDiagram
  data={data}
  from="a"
  to="b"
  value="trips"
  order={["Harbour", "Quay", "Market", "Town Hall", "University", "Park", "Hospital", "Stadium", "Airport"]}
  colorBy="none"
  format="integer"
  title="Harbour and Market stations exchanged 4,200 trips a day"
  subtitle="Daily trips between pairs of stations on one tram line, both directions; dots show each station's total"
  note="Illustrative figures for an invented line."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "arc-diagram",
  "data": [
    { "a": "Harbour", "b": "Market", "trips": 4200 },
    { "a": "Harbour", "b": "Quay", "trips": 900 },
    { "a": "Quay", "b": "Market", "trips": 1300 },
    { "a": "Market", "b": "Town Hall", "trips": 2600 },
    { "a": "Market", "b": "University", "trips": 3100 },
    { "a": "Town Hall", "b": "University", "trips": 1500 },
    { "a": "Town Hall", "b": "Hospital", "trips": 1100 },
    { "a": "University", "b": "Park", "trips": 800 },
    { "a": "University", "b": "Airport", "trips": 1900 },
    { "a": "Park", "b": "Hospital", "trips": 600 },
    { "a": "Hospital", "b": "Stadium", "trips": 700 },
    { "a": "Stadium", "b": "Airport", "trips": 1200 },
    { "a": "Harbour", "b": "Airport", "trips": 2300 },
    { "a": "Market", "b": "Stadium", "trips": 1700 },
    { "a": "Quay", "b": "University", "trips": 500 }
  ],
  "from": "a",
  "to": "b",
  "value": "trips",
  "order": ["Harbour", "Quay", "Market", "Town Hall", "University", "Park", "Hospital", "Stadium", "Airport"],
  "colorBy": "none",
  "format": "integer",
  "title": "Harbour and Market stations exchanged 4,200 trips a day",
  "subtitle": "Daily trips between pairs of stations on one tram line, both directions; dots show each station's total",
  "note": "Illustrative figures for an invented line."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `from` (required) | `string` |  | Field naming one end of each connection. With `select: true` a click selects the entity under this field name, so inside `<InsightData>` other charts are filtered on `from`; pass `select: "<field>"` to link on the field that holds the entity in the shared rows. |
| `to` (required) | `string` |  | Field naming the other end. |
| `value` | `string` |  | Value field: arc thickness. Omit to count rows. Rows joining the same pair are summed, in either direction. |
| `order` | `string[]` |  | Entity names in the order they sit on the line. Entities not listed follow in data order. |
| `orientation` | `"auto" \| "horizontal" \| "vertical"` | `"auto"` | Line along the bottom with arcs above, or down the left with arcs to the right. Auto turns vertical on narrow screens. |
| `colorBy` | `"series" \| "none"` |  | `series`: each arc in the colour of its first entity; past the size of the theme's palette the extra colours are derived from the theme's own. `none`: every arc in the accent. Default: series while the entities fit the palette (at most 8), none beyond. |
| `arcLabels` | `boolean` | `true` | Print values at the top of the arcs, largest first, wherever they do not collide. The values that do not fit are printed while their entity is hovered or selected, and every value is in the tooltip. |
| `names` | `Record<string, string>` |  | Display names for entity keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [network-poster](https://insightcharts.dev/llms/network-poster.md)

### More examples

#### One entity highlighted

```tsx
import { ArcDiagram } from "insightcharts";

const data = [
  { a: "Harbour", b: "Market", trips: 4200 },
  { a: "Harbour", b: "Quay", trips: 900 },
  { a: "Quay", b: "Market", trips: 1300 },
  { a: "Market", b: "Town Hall", trips: 2600 },
  { a: "Market", b: "University", trips: 3100 },
  { a: "Town Hall", b: "University", trips: 1500 },
  { a: "Town Hall", b: "Hospital", trips: 1100 },
  { a: "University", b: "Park", trips: 800 },
  // ... 7 more rows
];

<ArcDiagram
  data={data}
  from="a"
  to="b"
  value="trips"
  order={["Harbour", "Quay", "Market", "Town Hall", "University", "Park", "Hospital", "Stadium", "Airport"]}
  highlight="University"
  format="integer"
  title="University station had 7,800 daily trips to and from 5 other stations"
  subtitle="Daily trips between pairs of stations on one tram line, both directions"
  note="Illustrative figures for an invented line."
/>
```

#### Coloured by entity, counting rows

```tsx
import { ArcDiagram } from "insightcharts";

const data = [
  { a: "Ana", b: "Ben" },
  { a: "Ana", b: "Ben" },
  { a: "Ana", b: "Ben" },
  { a: "Ana", b: "Cleo" },
  { a: "Ben", b: "Cleo" },
  { a: "Ben", b: "Cleo" },
  { a: "Cleo", b: "Dev" },
  { a: "Cleo", b: "Dev" },
  // ... 9 more rows
];

<ArcDiagram
  data={data}
  from="a"
  to="b"
  title="Cleo and Dev shared 4 of the play's 17 two-person scenes"
  subtitle="Scenes shared by pairs of six characters in one play, in order of first appearance"
  note="Illustrative figures for an invented play."
/>
```

#### Ten entities, one colour each

```tsx
import { ArcDiagram } from "insightcharts";

const data = [
  { a: "Pier", b: "Docks", trips: 1800 },
  { a: "Pier", b: "Forum", trips: 2400 },
  { a: "Docks", b: "Canal", trips: 900 },
  { a: "Canal", b: "Forum", trips: 1500 },
  { a: "Forum", b: "Abbey", trips: 3300 },
  { a: "Forum", b: "Castle", trips: 1300 },
  { a: "Abbey", b: "Castle", trips: 1100 },
  { a: "Abbey", b: "Mills", trips: 700 },
  // ... 7 more rows
];

<ArcDiagram
  data={data}
  from="a"
  to="b"
  value="trips"
  order={["Pier", "Docks", "Canal", "Forum", "Abbey", "Castle", "Garden", "Mills", "Heath", "Depot"]}
  colorBy="series"
  format="integer"
  title="Forum and Abbey stations exchanged 3,300 trips a day"
  subtitle="Daily trips between pairs of ten stations on one tram line, both directions; each arc takes the colour of the station nearer the start of the line"
  note="Illustrative figures for an invented line."
/>
```

#### Stress: 18 entities with long names

```tsx
import { ArcDiagram } from "insightcharts";

const data = [
  { a: "Customer support", b: "Marketing", messages: 33 },
  { a: "Customer support", b: "Data platform", messages: 22 },
  { a: "Customer support", b: "Finance", messages: 14 },
  { a: "Customer support", b: "Research", messages: 8 },
  { a: "Billing", b: "Product design", messages: 222 },
  { a: "Billing", b: "Security", messages: 189 },
  { a: "Billing", b: "People team", messages: 158 },
  { a: "Billing", b: "Partnerships", messages: 130 },
  // ... 24 more rows
];

<ArcDiagram
  data={data}
  from="a"
  to="b"
  value="messages"
  order={[
    "Customer support",
    "Billing",
    "Sales, north region",
    "Sales, south region",
    "Marketing",
    "Product design",
    "Web engineering",
    "Mobile engineering",
    "Data platform",
    "Security",
    "Quality assurance",
    "Legal and compliance",
    "Finance",
    "People team",
    "Facilities",
    "Executive office",
    "Research",
    "Partnerships",
  ]}
  title="Messages between 18 teams in one week"
  subtitle="Messages exchanged between pairs of teams at one company, one week; dots show each team's total"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/arc-diagram.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/arc-diagram.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Area chart (`area-chart`)

> Shows a quantity over time as a filled area from zero: one series, stacked series, shares of 100%, or a streamgraph.

- Component: `AreaChart` (import from `insightcharts`)
- Spec type: `"area-chart"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A volume or cumulative quantity over time where the filled magnitude matters; stacked when the total and its composition both matter; percent when only the mix matters; stream for the changing mix of many series over a long period.

### Avoid

Comparing the trajectories of several series against each other (use line-chart: only the bottom band of a stack has a flat baseline); a few time points (use bar-chart with stack); more than about 6 bands.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/area-chart
```

The file lands at `components/insightcharts/atoms/area-chart.tsx`. `@insightcharts/area-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { AreaChart } from "insightcharts";

const data = [
  { year: "2014", gw: 180 },
  { year: "2015", gw: 229 },
  { year: "2016", gw: 306 },
  { year: "2017", gw: 405 },
  { year: "2018", gw: 512 },
  { year: "2019", gw: 633 },
  { year: "2020", gw: 774 },
  { year: "2021", gw: 945 },
  { year: "2022", gw: 1177 },
  { year: "2023", gw: 1610 },
];

<AreaChart
  data={data}
  x="year"
  y="gw"
  names={{ gw: "Installed solar capacity" }}
  format="{value} GW"
  title="World solar capacity rose from 180 GW in 2014 to 1,610 GW in 2023"
  subtitle="Cumulative installed solar PV capacity, gigawatts"
  source="IRENA, Renewable Capacity Statistics (rounded)"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "area-chart",
  "data": [
    { "year": "2014", "gw": 180 },
    { "year": "2015", "gw": 229 },
    { "year": "2016", "gw": 306 },
    { "year": "2017", "gw": 405 },
    { "year": "2018", "gw": 512 },
    { "year": "2019", "gw": 633 },
    { "year": "2020", "gw": 774 },
    { "year": "2021", "gw": 945 },
    { "year": "2022", "gw": 1177 },
    { "year": "2023", "gw": 1610 }
  ],
  "x": "year",
  "y": "gw",
  "names": { "gw": "Installed solar capacity" },
  "format": "{value} GW",
  "title": "World solar capacity rose from 180 GW in 2014 to 1,610 GW in 2023",
  "subtitle": "Cumulative installed solar PV capacity, gigawatts",
  "source": "IRENA, Renewable Capacity Statistics (rounded)",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Time or ordered category field. ISO dates are placed on a true time axis. |
| `y` (required) | `string \| string[]` |  | Value field, or several (one area each). |
| `series` | `string` |  | Field that splits rows into areas (long data). |
| `stack` | `boolean \| "percent"` | `false` | Stack the areas; `percent` normalises every x position to 100%. |
| `stream` | `boolean` | `false` | Streamgraph: stack around a centred baseline. The value axis is dropped because only band thickness is readable. |
| `curve` | `"linear" \| "smooth" \| "step"` | `"linear"` | Edge shape. A streamgraph defaults to smooth. |
| `labels` | `boolean` |  | Name each band inside itself where it fits; the rest go to the legend. Default: on when stacked. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md)

### More examples

#### Stacked, labelled in the bands

```tsx
import { AreaChart } from "insightcharts";

const data = [
  { year: "2000", Coal: 5990, Gas: 2770, Nuclear: 2540, Hydro: 2620, "Wind and solar": 32 },
  { year: "2004", Coal: 6940, Gas: 3450, Nuclear: 2700, Hydro: 2810, "Wind and solar": 88 },
  { year: "2008", Coal: 8260, Gas: 4300, Nuclear: 2660, Hydro: 3250, "Wind and solar": 233 },
  { year: "2012", Coal: 9170, Gas: 5100, Nuclear: 2400, Hydro: 3650, "Wind and solar": 630 },
  { year: "2016", Coal: 9450, Gas: 5800, Nuclear: 2540, Hydro: 4020, "Wind and solar": 1290 },
  { year: "2020", Coal: 9440, Gas: 6370, Nuclear: 2640, Hydro: 4350, "Wind and solar": 2440 },
  { year: "2024", Coal: 10590, Gas: 6790, Nuclear: 2770, Hydro: 4410, "Wind and solar": 4620 },
];

<AreaChart
  data={data}
  x="year"
  y={["Coal", "Gas", "Hydro", "Nuclear", "Wind and solar"]}
  stack
  format="compact"
  title="Wind and solar generated 4,620 TWh of electricity in 2024"
  subtitle="World electricity generation by source, terawatt-hours"
  source="Ember, Global Electricity Review (rounded)"
  note="Figures are approximate, for illustration"
/>
```

#### 100% stacked with highlight

```tsx
import { AreaChart } from "insightcharts";

const data = [
  { year: "2000", Coal: 5990, Gas: 2770, Nuclear: 2540, Hydro: 2620, "Wind and solar": 32 },
  { year: "2004", Coal: 6940, Gas: 3450, Nuclear: 2700, Hydro: 2810, "Wind and solar": 88 },
  { year: "2008", Coal: 8260, Gas: 4300, Nuclear: 2660, Hydro: 3250, "Wind and solar": 233 },
  { year: "2012", Coal: 9170, Gas: 5100, Nuclear: 2400, Hydro: 3650, "Wind and solar": 630 },
  { year: "2016", Coal: 9450, Gas: 5800, Nuclear: 2540, Hydro: 4020, "Wind and solar": 1290 },
  { year: "2020", Coal: 9440, Gas: 6370, Nuclear: 2640, Hydro: 4350, "Wind and solar": 2440 },
  { year: "2024", Coal: 10590, Gas: 6790, Nuclear: 2770, Hydro: 4410, "Wind and solar": 4620 },
];

<AreaChart
  data={data}
  x="year"
  y={["Coal", "Gas", "Hydro", "Nuclear", "Wind and solar"]}
  stack="percent"
  highlight="Wind and solar"
  title="Wind and solar's share of electricity rose from 0.2% in 2000 to 15.8% in 2024"
  subtitle="Share of world electricity generation"
  source="Ember, Global Electricity Review (rounded)"
  note="Figures are approximate, for illustration"
/>
```

#### Streamgraph, long format

```tsx
import { AreaChart } from "insightcharts";

const data = [
  { month: "2021-01-01", genre: "Drama", hours: 58 },
  { month: "2021-02-01", genre: "Drama", hours: 58 },
  { month: "2021-03-01", genre: "Drama", hours: 58 },
  { month: "2021-04-01", genre: "Drama", hours: 55 },
  { month: "2021-05-01", genre: "Drama", hours: 50 },
  { month: "2021-06-01", genre: "Drama", hours: 45 },
  { month: "2021-07-01", genre: "Drama", hours: 38 },
  { month: "2021-08-01", genre: "Drama", hours: 31 },
  // ... 280 more rows
];

<AreaChart
  data={data}
  x="month"
  y="hours"
  series="genre"
  stream
  format="{value}m hours"
  title="Monthly hours watched by genre, 2021 to 2024"
  subtitle="Millions of hours per month, six genres"
  note="Illustrative data"
/>
```

#### Overlapping washes

```tsx
import { AreaChart } from "insightcharts";

const data = [
  { "2023": 41, "2024": 52, month: "Jan" },
  { "2023": 44, "2024": 55, month: "Feb" },
  { "2023": 58, "2024": 71, month: "Mar" },
  { "2023": 73, "2024": 80, month: "Apr" },
  { "2023": 96, "2024": 104, month: "May" },
  { "2023": 118, "2024": 131, month: "Jun" },
  { "2023": 134, "2024": 152, month: "Jul" },
  { "2023": 129, "2024": 147, month: "Aug" },
  // ... 4 more rows
];

<AreaChart
  data={data}
  x="month"
  y={["2023", "2024"]}
  curve="smooth"
  format="{value}k"
  title="July bike-share trips rose from 134,000 in 2023 to 152,000 in 2024"
  subtitle="Bike-share trips per month, thousands"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/area-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/area-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Arrow chart (`arrow-chart`)

> Draws an arrow per category from a start value to an end value, showing the direction and size of each shift.

- Component: `ArrowChart` (import from `insightcharts`)
- Spec type: `"arrow-chart"`
- Level: atom. Category: comparison.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Shifts between two moments across up to about 25 categories when some rise and some fall: swings between elections, before / after a policy.

### Avoid

When both levels matter more than the direction (use dumbbell-chart); more than two points in time (use slope-chart or line-chart); a single value per category (use bar-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/arrow-chart
```

The file lands at `components/insightcharts/atoms/arrow-chart.tsx`. `@insightcharts/arrow-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ArrowChart } from "insightcharts";

const data = [
  { group: "Under 30", y2019: 62, y2024: 71 },
  { group: "30 to 44", y2019: 58, y2024: 63 },
  { group: "45 to 64", y2019: 49, y2024: 47 },
  { group: "65 and over", y2019: 41, y2024: 34 },
];

<ArrowChart
  data={data}
  category="group"
  from="y2019"
  to="y2024"
  names={{ y2019: "2019", y2024: "2024" }}
  format="{value}%"
  changeLabel="Change"
  height={220}
  title="Support among under-30s rose from 62% in 2019 to 71% in 2024"
  subtitle="Share in favour of the congestion charge, by age group, 2019 to 2024"
  source="City residents survey"
  note="Illustrative figures."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "arrow-chart",
  "data": [
    { "group": "Under 30", "y2019": 62, "y2024": 71 },
    { "group": "30 to 44", "y2019": 58, "y2024": 63 },
    { "group": "45 to 64", "y2019": 49, "y2024": 47 },
    { "group": "65 and over", "y2019": 41, "y2024": 34 }
  ],
  "category": "group",
  "from": "y2019",
  "to": "y2024",
  "names": { "y2019": "2019", "y2024": "2024" },
  "format": "{value}%",
  "changeLabel": "Change",
  "height": 220,
  "title": "Support among under-30s rose from 62% in 2019 to 71% in 2024",
  "subtitle": "Share in favour of the congestion charge, by age group, 2019 to 2024",
  "source": "City residents survey",
  "note": "Illustrative figures."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `category` (required) | `string` |  | Category field: one arrow each. |
| `from` (required) | `string` |  | Field with the start value, or (long data) the `series` value that marks it. |
| `to` (required) | `string` |  | Field with the end value, or (long data) the `series` value that marks it. |
| `series` | `string` |  | Long data: the field whose values are `from` and `to`. |
| `value` | `string` | `"value"` | Long data: the measure field. |
| `good` | `"up" \| "down" \| "none"` | `"up"` | Direction drawn in the positive colour. `none` uses the accent for every arrow. |
| `sort` | `"change" \| "from" \| "to" \| "none"` | `"change"` | Row order. |
| `order` | `"desc" \| "asc"` | `"desc"` | Sort direction. |
| `labels` | `boolean` |  | Start and end values at the tail and head. Default: on for up to 14 rows; otherwise a value axis is drawn. |
| `changeLabel` | `boolean \| string` | `false` | Print the signed change in a right-hand column; a string sets the column header. |
| `zero` | `boolean` | `false` | Start the value axis at zero. |
| `names` | `Record<string, string>` |  | Display names for the `from` and `to` keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Lower is better, one row highlighted

```tsx
import { ArrowChart } from "insightcharts";

const data = [
  { country: "Greece", before: 27.5, after: 10.1 },
  { country: "Spain", before: 26.1, after: 11.4 },
  { country: "Portugal", before: 16.2, after: 6.4 },
  { country: "Italy", before: 12.1, after: 6.5 },
  { country: "France", before: 10.3, after: 7.4 },
  { country: "Germany", before: 5.2, after: 3.4 },
  { country: "Austria", before: 5.3, after: 5.2 },
  { country: "Luxembourg", before: 5.9, after: 6.1 },
];

<ArrowChart
  data={data}
  category="country"
  from="before"
  to="after"
  names={{ before: "2013", after: "2024" }}
  good="down"
  highlight="Greece"
  sort="change"
  order="asc"
  format="{value}%"
  title="Greek unemployment fell from 27.5% in 2013 to 10.1% in 2024"
  subtitle="Unemployment rate, 2013 to 2024"
  source="Eurostat (rounded)"
  note="Figures are approximate, for illustration"
/>
```

#### Long format

```tsx
import { ArrowChart } from "insightcharts";

const data = [
  { party: "Greens", election: "2019", value: 20.5 },
  { party: "Greens", election: "2024", value: 11.9 },
  { party: "Conservatives", election: "2019", value: 28.9 },
  { party: "Conservatives", election: "2024", value: 30 },
  { party: "Social Democrats", election: "2019", value: 15.8 },
  { party: "Social Democrats", election: "2024", value: 13.9 },
  { party: "Far right", election: "2019", value: 11 },
  { party: "Far right", election: "2024", value: 15.9 },
  // ... 2 more rows
];

<ArrowChart
  data={data}
  category="party"
  series="election"
  from="2019"
  to="2024"
  good="none"
  changeLabel="Swing"
  format="{value}%"
  height={250}
  title="The Greens' vote share fell from 20.5% in 2019 to 11.9% in 2024"
  subtitle="Vote share in the European Parliament election, Germany, 2019 to 2024"
  source="Federal Returning Officer"
  note="Figures are approximate, for illustration"
/>
```

#### Stress: 24 rows on a value axis

```tsx
import { ArrowChart } from "insightcharts";

const data = [
  { region: "Northumberland and Durham coalfield towns", before: 31, after: 48 },
  { region: "Greater Manchester", before: 44, after: 52 },
  { region: "West Midlands conurbation", before: 41, after: 47 },
  { region: "Merseyside", before: 47, after: 50 },
  { region: "South Yorkshire", before: 36, after: 49 },
  { region: "West Yorkshire", before: 42, after: 48 },
  { region: "Tyne and Wear", before: 45, after: 51 },
  { region: "Inner London", before: 58, after: 49 },
  // ... 16 more rows
];

<ArrowChart
  data={data}
  category="region"
  from="before"
  to="after"
  names={{ before: "Last election", after: "This election" }}
  good="none"
  format="{value}%"
  title="The winning party's vote share in Lincolnshire rose from 20% to 38%"
  subtitle="Vote share of the winning party, by region"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/arrow-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/arrow-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Bar chart (`bar-chart`)

> Compares a value across categories with bars from a zero baseline.

- Component: `BarChart` (import from `insightcharts`)
- Spec type: `"bar-chart"`
- Level: atom. Category: comparison.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Ranking or comparing up to about 20 categories; grouped for a few series, stacked when the total and its composition both matter.

### Avoid

Change over many time points (use line-chart); two values per category (use dumbbell-chart); more than about 5 stacked segments.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/bar-chart
```

The file lands at `components/insightcharts/atoms/bar-chart.tsx`. `@insightcharts/bar-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart } from "insightcharts";

const data = [
  { country: "Norway", share: 98 },
  { country: "Brazil", share: 89 },
  { country: "Canada", share: 68 },
];

<BarChart
  data={data}
  x="country"
  y="share"
  format="{value}%"
  title="Renewables supplied 98% of Norway's electricity in 2023"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "bar-chart",
  "data": [
    { "country": "Norway", "share": 98 },
    { "country": "Brazil", "share": 89 },
    { "country": "Canada", "share": 68 }
  ],
  "x": "country",
  "y": "share",
  "format": "{value}%",
  "title": "Renewables supplied 98% of Norway's electricity in 2023"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Category field. |
| `y` (required) | `string \| string[]` |  | Value field, or several for grouped / stacked bars. |
| `series` | `string` |  | Field that splits rows into series (long data). |
| `orientation` | `"auto" \| "horizontal" \| "vertical"` | `"auto"` | Horizontal for rankings and long labels, vertical for time. |
| `sort` | `"none" \| "asc" \| "desc"` |  | Bar order. Default: descending for rankings, data order for time. |
| `stack` | `boolean \| "percent"` | `false` | Stack series; `percent` normalises to 100%. |
| `labels` | `boolean` |  | Value labels at bar ends. Default: on for one series of up to 12 bars. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [before-after](https://insightcharts.dev/llms/before-after.md), [chart-callout](https://insightcharts.dev/llms/chart-callout.md), [chart-tabs](https://insightcharts.dev/llms/chart-tabs.md), [linked-charts](https://insightcharts.dev/llms/linked-charts.md), [poster](https://insightcharts.dev/llms/poster.md), [scrolly-chart](https://insightcharts.dev/llms/scrolly-chart.md), [section](https://insightcharts.dev/llms/section.md), [small-multiple-grid](https://insightcharts.dev/llms/small-multiple-grid.md), [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md), [data-explorer](https://insightcharts.dev/llms/data-explorer.md), [executive-brief](https://insightcharts.dev/llms/executive-brief.md), [explainer](https://insightcharts.dev/llms/explainer.md), [report-page](https://insightcharts.dev/llms/report-page.md), [scorecard](https://insightcharts.dev/llms/scorecard.md), [social-card](https://insightcharts.dev/llms/social-card.md), [story-deck](https://insightcharts.dev/llms/story-deck.md), [timeline-story](https://insightcharts.dev/llms/timeline-story.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Two bars, horizontal

```tsx
import { BarChart } from "insightcharts";

const data = [{ group: "Renters under 35", share: 46 }, { group: "Owners under 35", share: 21 }];

<BarChart
  data={data}
  x="group"
  y="share"
  format="{value}%"
  title="46% of renters under 35 moved home in the past year"
  subtitle="Share who moved home in the past 12 months"
  note="Illustrative figures."
/>
```

#### Vertical over time with a target line

```tsx
import { BarChart } from "insightcharts";

const data = [
  { year: "2019", gw: 98 },
  { year: "2020", gw: 127 },
  { year: "2021", gw: 168 },
  { year: "2022", gw: 239 },
  { year: "2023", gw: 407 },
  { year: "2024", gw: 452 },
];

<BarChart
  data={data}
  x="year"
  y="gw"
  sort="none"
  orientation="vertical"
  format="{value} GW"
  annotations={[
    { type: "line", axis: "y", value: 300, label: "Forecast" },
    { type: "band", axis: "x", from: "2020", to: "2021", label: "Pandemic" },
  ]}
  title="The world added 452 GW of solar capacity in 2024"
  subtitle="New solar capacity added worldwide per year, gigawatts"
  note="Illustrative figures."
/>
```

#### Grouped, horizontal, highlighted

```tsx
import { BarChart } from "insightcharts";

const data = [
  { region: "Sub-Saharan Africa", y2000: 26, y2023: 51 },
  { region: "South Asia", y2000: 58, y2023: 99 },
  { region: "Latin America", y2000: 92, y2023: 98 },
  { region: "East Asia and Pacific", y2000: 88, y2023: 99 },
];

<BarChart
  data={data}
  x="region"
  y={["y2000", "y2023"]}
  names={{ y2000: "2000", y2023: "2023" }}
  highlight="y2023"
  format="{value}%"
  title="Electricity access in South Asia rose from 58% in 2000 to 99% in 2023"
  subtitle="Share of population with access to electricity"
  source="World Bank (rounded)"
  note="Figures are approximate, for illustration"
/>
```

#### Stacked to 100%

```tsx
import { BarChart } from "insightcharts";

const data = [
  { age: "18 to 29", Daily: 71, Weekly: 19, Rarely: 10 },
  { age: "30 to 49", Daily: 58, Weekly: 25, Rarely: 17 },
  { age: "50 to 64", Daily: 39, Weekly: 28, Rarely: 33 },
  { age: "65 and over", Daily: 22, Weekly: 24, Rarely: 54 },
];

<BarChart
  data={data}
  x="age"
  y={["Daily", "Weekly", "Rarely"]}
  stack="percent"
  orientation="horizontal"
  title="71% of adults aged 18 to 29 watch short-form video daily"
  subtitle="How often adults watch short-form video, by age group"
  note="Illustrative figures."
/>
```

#### Forced vertical with names too long for their bands

```tsx
import { BarChart } from "insightcharts";

const data = [
  { mode: "Private car", share: 46 },
  { mode: "Public transport", share: 24 },
  { mode: "Walking", share: 15 },
  { mode: "Cycling and scooters", share: 9 },
  { mode: "Taxi and ride-hailing", share: 4 },
  { mode: "Other", share: 2 },
];

<BarChart
  data={data}
  x="mode"
  y="share"
  orientation="vertical"
  format="{value}%"
  height={260}
  title="46% of commuters travel to work by private car"
  subtitle="Main mode of travel to work, share of commuters"
  note="Illustrative figures. Long category labels wrap, then rotate."
/>
```

#### Stress: 18 long category names

```tsx
import { BarChart } from "insightcharts";

const data = [
  { sector: "Professional, scientific and technical services", share: 64 },
  { sector: "Information and communication", share: 63 },
  { sector: "Financial and insurance activities", share: 62 },
  { sector: "Public administration and defence", share: 55 },
  { sector: "Education", share: 54 },
  { sector: "Real estate activities", share: 48 },
  { sector: "Administrative and support services", share: 47 },
  { sector: "Arts, entertainment and recreation", share: 46 },
  // ... 10 more rows
];

<BarChart
  data={data}
  x="sector"
  y="share"
  labels
  format="{value}%"
  title="64% of professional, scientific and technical staff work from home at least one day a week"
  subtitle="Share of employees working from home at least one day a week, by sector"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/bar-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/bar-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Beeswarm chart (`beeswarm-chart`)

> Shows a distribution as one dot per row along a value axis, with dots stacked sideways where they would collide.

- Component: `BeeswarmChart` (import from `insightcharts`)
- Spec type: `"beeswarm-chart"`
- Level: atom. Category: distribution.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Showing a distribution while keeping every individual visible: 30 to about 2,000 named things (countries, players, schools), optionally in a few rows by group, with one or two highlighted.

### Avoid

More than about 2,000 rows or when only the summary matters (use histogram or box-plot); many groups with few rows each (use strip-plot); two numeric measures (use scatter-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/beeswarm-chart
```

The file lands at `components/insightcharts/atoms/beeswarm-chart.tsx`. `@insightcharts/beeswarm-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BeeswarmChart } from "insightcharts";

const data = [
  { country: "Qatar", rate: 0.4 },
  { country: "Kuwait", rate: 0.6 },
  { country: "UAE", rate: 0.9 },
  { country: "Saudi Arabia", rate: 1.2 },
  { country: "Japan", rate: 2.5 },
  { country: "Italy", rate: 2.9 },
  { country: "Germany", rate: 3 },
  { country: "United States", rate: 3.6 },
  { country: "France", rate: 3.1 },
  { country: "Spain", rate: 3.3 },
  { country: "United Kingdom", rate: 3.4 },
  { country: "Canada", rate: 3.2 },
  { country: "Australia", rate: 3.1 },
  { country: "South Korea", rate: 2.4 },
  { country: "Netherlands", rate: 2.8 },
  { country: "Sweden", rate: 2.6 },
  { country: "Norway", rate: 2.5 },
  { country: "Switzerland", rate: 2.3 },
  { country: "Poland", rate: 4.2 },
  { country: "Portugal", rate: 3.1 },
  { country: "Greece", rate: 3.9 },
  { country: "Ireland", rate: 2.7 },
  { country: "Denmark", rate: 2.4 },
  { country: "Finland", rate: 2.9 },
  { country: "Austria", rate: 2.7 },
  { country: "Belgium", rate: 2.9 },
  { country: "Czechia", rate: 3.4 },
  { country: "Hungary", rate: 4.4 },
  { country: "Romania", rate: 5.6 },
  { country: "Bulgaria", rate: 5.9 },
  { country: "Mexico", rate: 12.4 },
  { country: "Brazil", rate: 14.2 },
  { country: "Argentina", rate: 9.8 },
  { country: "Chile", rate: 7.9 },
  { country: "Colombia", rate: 13.1 },
  { country: "Peru", rate: 11.6 },
  { country: "China", rate: 6.3 },
  { country: "India", rate: 26.6 },
  { country: "Indonesia", rate: 21 },
  { country: "Vietnam", rate: 19.8 },
  { country: "Thailand", rate: 8.1 },
  { country: "Malaysia", rate: 7.4 },
  { country: "Philippines", rate: 24.3 },
  { country: "Pakistan", rate: 55.8 },
  { country: "Bangladesh", rate: 28.9 },
  { country: "Turkey", rate: 9.1 },
  { country: "Iran", rate: 12 },
  { country: "Egypt", rate: 19.2 },
  { country: "South Africa", rate: 33.5 },
  { country: "Kenya", rate: 37.2 },
  { country: "Ghana", rate: 42.1 },
  { country: "Ethiopia", rate: 46.8 },
  { country: "Tanzania", rate: 44.3 },
  { country: "Uganda", rate: 41 },
  { country: "Nigeria", rate: 107.2 },
  { country: "Niger", rate: 115.2 },
  { country: "Chad", rate: 101.1 },
  { country: "Mali", rate: 94 },
  { country: "Somalia", rate: 106.1 },
  { country: "Sierra Leone", rate: 100.8 },
  { country: "DR Congo", rate: 76 },
  { country: "Angola", rate: 66.5 },
  { country: "Mozambique", rate: 67.2 },
  { country: "Cameroon", rate: 69.8 },
  { country: "Senegal", rate: 37.4 },
  { country: "Rwanda", rate: 38.3 },
  { country: "Zambia", rate: 56.2 },
  { country: "Sudan", rate: 52.9 },
  { country: "Afghanistan", rate: 55.5 },
  { country: "Yemen", rate: 39.9 },
  { country: "Haiti", rate: 56.3 },
  { country: "Bolivia", rate: 23.7 },
  { country: "Guatemala", rate: 22.1 },
  { country: "Nepal", rate: 26.2 },
  { country: "Myanmar", rate: 40.1 },
  { country: "Cambodia", rate: 23.6 },
  { country: "Morocco", rate: 16.7 },
  { country: "Algeria", rate: 21.5 },
  { country: "Iraq", rate: 23.4 },
  { country: "Ukraine", rate: 7.8 },
  { country: "Russia", rate: 4.8 },
  { country: "Kazakhstan", rate: 9.7 },
  { country: "Uzbekistan", rate: 13.6 },
  { country: "Sri Lanka", rate: 6.4 },
];

<BeeswarmChart
  data={data}
  value="rate"
  label="country"
  highlight={["Nigeria", "India", "United States"]}
  title="Nigeria had 107.2 under-five deaths per 1,000 live births in 2022"
  subtitle="Deaths before age five per 1,000 live births, 84 countries, 2022"
  source="UN IGME (rounded)"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "beeswarm-chart",
  "data": [
    { "country": "Qatar", "rate": 0.4 },
    { "country": "Kuwait", "rate": 0.6 },
    { "country": "UAE", "rate": 0.9 },
    { "country": "Saudi Arabia", "rate": 1.2 },
    { "country": "Japan", "rate": 2.5 },
    { "country": "Italy", "rate": 2.9 },
    { "country": "Germany", "rate": 3 },
    { "country": "United States", "rate": 3.6 },
    { "country": "France", "rate": 3.1 },
    { "country": "Spain", "rate": 3.3 },
    { "country": "United Kingdom", "rate": 3.4 },
    { "country": "Canada", "rate": 3.2 },
    { "country": "Australia", "rate": 3.1 },
    { "country": "South Korea", "rate": 2.4 },
    { "country": "Netherlands", "rate": 2.8 },
    { "country": "Sweden", "rate": 2.6 },
    { "country": "Norway", "rate": 2.5 },
    { "country": "Switzerland", "rate": 2.3 },
    { "country": "Poland", "rate": 4.2 },
    { "country": "Portugal", "rate": 3.1 },
    { "country": "Greece", "rate": 3.9 },
    { "country": "Ireland", "rate": 2.7 },
    { "country": "Denmark", "rate": 2.4 },
    { "country": "Finland", "rate": 2.9 },
    { "country": "Austria", "rate": 2.7 },
    { "country": "Belgium", "rate": 2.9 },
    { "country": "Czechia", "rate": 3.4 },
    { "country": "Hungary", "rate": 4.4 },
    { "country": "Romania", "rate": 5.6 },
    { "country": "Bulgaria", "rate": 5.9 },
    { "country": "Mexico", "rate": 12.4 },
    { "country": "Brazil", "rate": 14.2 },
    { "country": "Argentina", "rate": 9.8 },
    { "country": "Chile", "rate": 7.9 },
    { "country": "Colombia", "rate": 13.1 },
    { "country": "Peru", "rate": 11.6 },
    { "country": "China", "rate": 6.3 },
    { "country": "India", "rate": 26.6 },
    { "country": "Indonesia", "rate": 21 },
    { "country": "Vietnam", "rate": 19.8 },
    { "country": "Thailand", "rate": 8.1 },
    { "country": "Malaysia", "rate": 7.4 },
    { "country": "Philippines", "rate": 24.3 },
    { "country": "Pakistan", "rate": 55.8 },
    { "country": "Bangladesh", "rate": 28.9 },
    { "country": "Turkey", "rate": 9.1 },
    { "country": "Iran", "rate": 12 },
    { "country": "Egypt", "rate": 19.2 },
    { "country": "South Africa", "rate": 33.5 },
    { "country": "Kenya", "rate": 37.2 },
    { "country": "Ghana", "rate": 42.1 },
    { "country": "Ethiopia", "rate": 46.8 },
    { "country": "Tanzania", "rate": 44.3 },
    { "country": "Uganda", "rate": 41 },
    { "country": "Nigeria", "rate": 107.2 },
    { "country": "Niger", "rate": 115.2 },
    { "country": "Chad", "rate": 101.1 },
    { "country": "Mali", "rate": 94 },
    { "country": "Somalia", "rate": 106.1 },
    { "country": "Sierra Leone", "rate": 100.8 },
    { "country": "DR Congo", "rate": 76 },
    { "country": "Angola", "rate": 66.5 },
    { "country": "Mozambique", "rate": 67.2 },
    { "country": "Cameroon", "rate": 69.8 },
    { "country": "Senegal", "rate": 37.4 },
    { "country": "Rwanda", "rate": 38.3 },
    { "country": "Zambia", "rate": 56.2 },
    { "country": "Sudan", "rate": 52.9 },
    { "country": "Afghanistan", "rate": 55.5 },
    { "country": "Yemen", "rate": 39.9 },
    { "country": "Haiti", "rate": 56.3 },
    { "country": "Bolivia", "rate": 23.7 },
    { "country": "Guatemala", "rate": 22.1 },
    { "country": "Nepal", "rate": 26.2 },
    { "country": "Myanmar", "rate": 40.1 },
    { "country": "Cambodia", "rate": 23.6 },
    { "country": "Morocco", "rate": 16.7 },
    { "country": "Algeria", "rate": 21.5 },
    { "country": "Iraq", "rate": 23.4 },
    { "country": "Ukraine", "rate": 7.8 },
    { "country": "Russia", "rate": 4.8 },
    { "country": "Kazakhstan", "rate": 9.7 },
    { "country": "Uzbekistan", "rate": 13.6 },
    { "country": "Sri Lanka", "rate": 6.4 }
  ],
  "value": "rate",
  "label": "country",
  "highlight": ["Nigeria", "India", "United States"],
  "title": "Nigeria had 107.2 under-five deaths per 1,000 live births in 2022",
  "subtitle": "Deaths before age five per 1,000 live births, 84 countries, 2022",
  "source": "UN IGME (rounded)",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `string` |  | Numeric field that positions each dot along the axis. |
| `group` | `string` |  | Field that splits the dots into rows, one swarm per group. |
| `series` | `string` |  | Field that colours dots by category. Beyond 6 categories the rest turn grey. |
| `label` | `string` |  | Field naming each dot, for tooltips, `highlight` and labels on highlighted dots. |
| `radius` | `number` |  | Dot radius in px. Default 5 down to 3 by row count; shrinks if a swarm would overflow its row. |
| `median` | `boolean` | `false` | Mark each row's median with a vertical tick. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Rows by group, with medians

```tsx
import { BeeswarmChart } from "insightcharts";

const data = [
  { player: "Guard 1", position: "Guard", height: 194 },
  { player: "Guard 2", position: "Guard", height: 194 },
  { player: "Guard 3", position: "Guard", height: 191 },
  { player: "Guard 4", position: "Guard", height: 187 },
  { player: "Guard 5", position: "Guard", height: 189 },
  { player: "Guard 6", position: "Guard", height: 188 },
  { player: "Guard 7", position: "Guard", height: 192 },
  { player: "Guard 8", position: "Guard", height: 191 },
  // ... 372 more rows
];

<BeeswarmChart
  data={data}
  value="height"
  group="position"
  label="player"
  median
  format="{value} cm"
  height={380}
  title="Height of 380 professional basketball players by position"
  subtitle="Height in centimetres. The tick marks the median of each position."
  note="Illustrative data"
/>
```

#### Colour by series, long format

```tsx
import { BeeswarmChart } from "insightcharts";

const data = [
  { person: "Engineering 1", team: "Engineering", level: "Junior", salary: 112 },
  { person: "Engineering 2", team: "Engineering", level: "Junior", salary: 109 },
  { person: "Engineering 3", team: "Engineering", level: "Junior", salary: 114 },
  { person: "Engineering 4", team: "Engineering", level: "Junior", salary: 127 },
  { person: "Engineering 5", team: "Engineering", level: "Senior", salary: 154 },
  { person: "Engineering 6", team: "Engineering", level: "Junior", salary: 127 },
  { person: "Engineering 7", team: "Engineering", level: "Lead", salary: 170 },
  { person: "Engineering 8", team: "Engineering", level: "Junior", salary: 124 },
  // ... 202 more rows
];

<BeeswarmChart
  data={data}
  value="salary"
  group="team"
  series="level"
  label="person"
  format="${value}k"
  height={420}
  title="Base salary by team and level"
  subtitle="Thousands of dollars, 210 employees"
  note="Illustrative data"
/>
```

#### Highlight a whole row

```tsx
import { BeeswarmChart } from "insightcharts";

const data = [
  { person: "Engineering 1", team: "Engineering", level: "Junior", salary: 112 },
  { person: "Engineering 2", team: "Engineering", level: "Junior", salary: 109 },
  { person: "Engineering 3", team: "Engineering", level: "Junior", salary: 114 },
  { person: "Engineering 4", team: "Engineering", level: "Junior", salary: 127 },
  { person: "Engineering 5", team: "Engineering", level: "Senior", salary: 154 },
  { person: "Engineering 6", team: "Engineering", level: "Junior", salary: 127 },
  { person: "Engineering 7", team: "Engineering", level: "Lead", salary: 170 },
  { person: "Engineering 8", team: "Engineering", level: "Junior", salary: 124 },
  // ... 202 more rows
];

<BeeswarmChart
  data={data}
  value="salary"
  group="team"
  label="person"
  highlight="Support"
  format="${value}k"
  height={380}
  title="Base salary by team"
  subtitle="Thousands of dollars, 210 employees. Support is highlighted."
  note="Illustrative data"
/>
```

#### Stress: 2,000 dots

```tsx
import { BeeswarmChart } from "insightcharts";

const data = [
  { id: "Trip 1", minutes: 28.8 },
  { id: "Trip 2", minutes: 17.1 },
  { id: "Trip 3", minutes: 17.1 },
  { id: "Trip 4", minutes: 16.4 },
  { id: "Trip 5", minutes: 32.2 },
  { id: "Trip 6", minutes: 16.8 },
  { id: "Trip 7", minutes: 14.4 },
  { id: "Trip 8", minutes: 15.8 },
  // ... 1992 more rows
];

<BeeswarmChart
  data={data}
  value="minutes"
  label="id"
  format="{value} min"
  height={420}
  title="Duration of 2,000 bike-share trips"
  subtitle="Minutes per trip"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/beeswarm-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/beeswarm-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Big number (`big-number`)

> A featured statistic with its label, change and the context that gives it meaning.

- Component: `BigNumber` (import from `insightcharts`)
- Spec type: `"big-number"`
- Level: atom. Category: figure.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

A single headline figure, or a row of three or four key numbers. Always give it context: a comparison, a denominator or a period.

### Avoid

Showing a number with no comparison; using a gauge or a one-slice donut for the same job.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/big-number
```

The file lands at `components/insightcharts/atoms/big-number.tsx`. `@insightcharts/big-number-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BigNumber } from "insightcharts";

<BigNumber
  value={0.317}
  format="percent"
  label="Share of global electricity from renewables"
  delta={0.021}
  deltaLabel="vs 2023"
  context="Up from 19% in 2010"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "big-number",
  "value": 0.317,
  "format": "percent",
  "label": "Share of global electricity from renewables",
  "delta": 0.021,
  "deltaLabel": "vs 2023",
  "context": "Up from 19% in 2010"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `number \| string` |  | The figure. Numbers are formatted with `format`. |
| `label` (required) | `string` |  | What it measures, sentence case. |
| `context` | `string` |  | The comparison, denominator or period that gives it meaning. |
| `delta` | `number \| string` |  | Change against a baseline. Numbers render as signed percentages (0.12 is +12%). |
| `deltaLabel` | `string` |  | What the delta is against, e.g. "vs last quarter". |
| `upIsGood` | `boolean` | `true` | Whether an increase is good news; decides the delta colour. |
| `format` | `FormatSpec` | `"auto"` | Number format. |
| `size` | `"hero" \| "stat"` | `"stat"` | `hero` for the one number a piece leads with. |
| `align` | `"left" \| "center"` | `"left"` | Text alignment. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [annotated-timeline](https://insightcharts.dev/llms/annotated-timeline.md), [before-after](https://insightcharts.dev/llms/before-after.md), [hero-figure](https://insightcharts.dev/llms/hero-figure.md), [metric-breakdown](https://insightcharts.dev/llms/metric-breakdown.md), [poster](https://insightcharts.dev/llms/poster.md), [quote-figure](https://insightcharts.dev/llms/quote-figure.md), [stat-row](https://insightcharts.dev/llms/stat-row.md), [explainer](https://insightcharts.dev/llms/explainer.md), [social-card](https://insightcharts.dev/llms/social-card.md), [story-deck](https://insightcharts.dev/llms/story-deck.md), [timeline-story](https://insightcharts.dev/llms/timeline-story.md)

### Links

- Registry item: https://insightcharts.dev/r/big-number.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/big-number.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Block bars (`block-bar`)

> Compares 3 to 12 values as thick rounded bars from a zero baseline, with each value printed inside the end of its bar and the category beneath.

- Component: `BlockBar` (import from `insightcharts`)
- Spec type: `"block-bar"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A short series or ranking that should read as a bold graphic with no axis: ticket sales in each of six years, two paired measures in five regions. Add `detail` for a second small figure above each bar and `marker` for an event between two bars.

### Avoid

More than 12 bars, more than two series or stacked parts (use bar-chart); negative values (use diverging-bar-chart); a long time series (use line-chart); values that differ by more than about 50 times, where the short bars vanish (use proportional-area).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/block-bar
```

The file lands at `components/insightcharts/atoms/block-bar.tsx`. `@insightcharts/block-bar-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BlockBar } from "insightcharts";

const data = [
  { year: "2020", tickets: 18400, seats: "41% of seats" },
  { year: "2021", tickets: 22900, seats: "49% of seats" },
  { year: "2022", tickets: 31200, seats: "58% of seats" },
  { year: "2023", tickets: 36800, seats: "64% of seats" },
  { year: "2024", tickets: 41500, seats: "69% of seats" },
  { year: "2025", tickets: 48200, seats: "74% of seats" },
];

<BlockBar
  data={data}
  name="year"
  value="tickets"
  detail="seats"
  format="integer"
  marker={{ after: "2021", label: "Second screen opened" }}
  title="The Portholm Film Festival sold 48,200 tickets in 2025"
  subtitle="Tickets sold per year and share of available seats filled, 2020 to 2025"
  source="Illustrative data"
  note="Invented figures for a fictional festival"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "block-bar",
  "data": [
    { "year": "2020", "tickets": 18400, "seats": "41% of seats" },
    { "year": "2021", "tickets": 22900, "seats": "49% of seats" },
    { "year": "2022", "tickets": 31200, "seats": "58% of seats" },
    { "year": "2023", "tickets": 36800, "seats": "64% of seats" },
    { "year": "2024", "tickets": 41500, "seats": "69% of seats" },
    { "year": "2025", "tickets": 48200, "seats": "74% of seats" }
  ],
  "name": "year",
  "value": "tickets",
  "detail": "seats",
  "format": "integer",
  "marker": { "after": "2021", "label": "Second screen opened" },
  "title": "The Portholm Film Festival sold 48,200 tickets in 2025",
  "subtitle": "Tickets sold per year and share of available seats filled, 2020 to 2025",
  "source": "Illustrative data",
  "note": "Invented figures for a fictional festival"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Category field: one bar (or one pair of bars) per value. |
| `value` (required) | `string \| string[]` |  | Value field, or two fields for paired bars. |
| `series` | `string` |  | Field that splits long-format rows into paired series. |
| `detail` | `string` |  | Field holding a short secondary label printed above each bar, e.g. "3.5% of GDP". |
| `marker` | `{ after: string; label?: string }` |  | A dotted line after the named category, marking an event, with an optional label. |
| `orientation` | `"auto" \| "vertical" \| "horizontal"` | `"auto"` | `auto` draws columns and switches to horizontal bars on narrow widths. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [count-poster](https://insightcharts.dev/llms/count-poster.md), [timeline-poster](https://insightcharts.dev/llms/timeline-poster.md)

### More examples

#### Paired series

```tsx
import { BlockBar } from "insightcharts";

const data = [
  { line: "Coast line", weekday: 41200, weekend: 26800 },
  { line: "Valley line", weekday: 33500, weekend: 12900 },
  { line: "Airport link", weekday: 27100, weekend: 29400 },
  { line: "Harbour loop", weekday: 15800, weekend: 9200 },
];

<BlockBar
  data={data}
  name="line"
  value={["weekday", "weekend"]}
  names={{ weekday: "Weekday", weekend: "Weekend day" }}
  format="compact"
  title="The Airport link carried 29,400 passengers on a weekend day"
  subtitle="Average daily passengers by rail line, weekdays and weekend days, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional network"
/>
```

#### Highlight, click to select

```tsx
import { BlockBar } from "insightcharts";

const data = [
  { country: "Norway", share: 89 },
  { country: "Sweden", share: 58 },
  { country: "Netherlands", share: 35 },
  { country: "Germany", share: 19 },
  { country: "Spain", share: 9 },
];

<BlockBar
  data={data}
  name="country"
  value="share"
  format="{value}%"
  highlight="Germany"
  select
  title="Battery electric cars were 19% of new cars sold in Germany in 2025"
  subtitle="Battery electric share of new passenger car sales, five countries, 2025"
  source="Illustrative data"
  note="Rounded, invented for illustration"
/>
```

#### Stress: twelve bars, long labels, uneven values

```tsx
import { BlockBar } from "insightcharts";

const data = [
  { port: "Greater Northern Container Terminal", teu: 9400, d: "31% of total" },
  { port: "Southport", teu: 6100, d: "20%" },
  { port: "Marlow Quay", teu: 4300, d: "14%" },
  { port: "Eastern Approaches Deepwater Port", teu: 3900, d: "13%" },
  { port: "Whitby Sands", teu: 2200, d: "7%" },
  { port: "Fenwick", teu: 1500, d: "5%" },
  { port: "Old Harbour", teu: 1100, d: "4%" },
  { port: "Tidewater", teu: 800, d: "3%" },
  // ... 4 more rows
];

<BlockBar
  data={data}
  name="port"
  value="teu"
  detail="d"
  format="integer"
  title="Greater Northern handled 9,400 thousand containers in 2025"
  subtitle="Container throughput by port, thousand TEU, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional country"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/block-bar.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/block-bar.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Box plot (`box-plot`)

> Summarises a numeric field per group as median, quartile box, whiskers and outlier dots, computed from raw rows.

- Component: `BoxPlot` (import from `insightcharts`)
- Spec type: `"box-plot"`
- Level: atom. Category: distribution.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Comparing the centre and spread of a numeric value across several groups, especially with many rows per group and an audience comfortable with quartiles.

### Avoid

A general audience or fewer than about 20 rows per group (use strip-plot or beeswarm-chart, which show the observations themselves); one group whose shape matters, such as two peaks, which a box hides (use histogram).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/box-plot
```

The file lands at `components/insightcharts/atoms/box-plot.tsx`. `@insightcharts/box-plot-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BoxPlot } from "insightcharts";

const data = [
  { department: "Emergency", minutes: 12 },
  { department: "Emergency", minutes: 18 },
  { department: "Emergency", minutes: 22 },
  { department: "Emergency", minutes: 25 },
  { department: "Emergency", minutes: 27 },
  { department: "Emergency", minutes: 31 },
  { department: "Emergency", minutes: 34 },
  { department: "Emergency", minutes: 38 },
  { department: "Emergency", minutes: 41 },
  { department: "Emergency", minutes: 44 },
  { department: "Emergency", minutes: 47 },
  { department: "Emergency", minutes: 52 },
  { department: "Emergency", minutes: 58 },
  { department: "Emergency", minutes: 63 },
  { department: "Emergency", minutes: 71 },
  { department: "Emergency", minutes: 84 },
  { department: "Emergency", minutes: 96 },
  { department: "Emergency", minutes: 131 },
  { department: "Emergency", minutes: 188 },
  { department: "Orthopaedics", minutes: 9 },
  { department: "Orthopaedics", minutes: 11 },
  { department: "Orthopaedics", minutes: 14 },
  { department: "Orthopaedics", minutes: 15 },
  { department: "Orthopaedics", minutes: 17 },
  { department: "Orthopaedics", minutes: 19 },
  { department: "Orthopaedics", minutes: 20 },
  { department: "Orthopaedics", minutes: 22 },
  { department: "Orthopaedics", minutes: 24 },
  { department: "Orthopaedics", minutes: 25 },
  { department: "Orthopaedics", minutes: 27 },
  { department: "Orthopaedics", minutes: 29 },
  { department: "Orthopaedics", minutes: 31 },
  { department: "Orthopaedics", minutes: 34 },
  { department: "Orthopaedics", minutes: 38 },
  { department: "Orthopaedics", minutes: 43 },
  { department: "Orthopaedics", minutes: 55 },
  { department: "Cardiology", minutes: 6 },
  { department: "Cardiology", minutes: 8 },
  { department: "Cardiology", minutes: 9 },
  { department: "Cardiology", minutes: 11 },
  { department: "Cardiology", minutes: 12 },
  { department: "Cardiology", minutes: 13 },
  { department: "Cardiology", minutes: 15 },
  { department: "Cardiology", minutes: 16 },
  { department: "Cardiology", minutes: 17 },
  { department: "Cardiology", minutes: 18 },
  { department: "Cardiology", minutes: 20 },
  { department: "Cardiology", minutes: 21 },
  { department: "Cardiology", minutes: 23 },
  { department: "Cardiology", minutes: 26 },
  { department: "Cardiology", minutes: 28 },
  { department: "Cardiology", minutes: 33 },
  { department: "Cardiology", minutes: 61 },
  { department: "Paediatrics", minutes: 4 },
  { department: "Paediatrics", minutes: 5 },
  { department: "Paediatrics", minutes: 7 },
  { department: "Paediatrics", minutes: 8 },
  { department: "Paediatrics", minutes: 9 },
  { department: "Paediatrics", minutes: 10 },
  { department: "Paediatrics", minutes: 11 },
  { department: "Paediatrics", minutes: 12 },
  { department: "Paediatrics", minutes: 12 },
  { department: "Paediatrics", minutes: 13 },
  { department: "Paediatrics", minutes: 14 },
  { department: "Paediatrics", minutes: 16 },
  { department: "Paediatrics", minutes: 17 },
  { department: "Paediatrics", minutes: 19 },
  { department: "Paediatrics", minutes: 22 },
  { department: "Paediatrics", minutes: 24 },
  { department: "Dermatology", minutes: 3 },
  { department: "Dermatology", minutes: 4 },
  { department: "Dermatology", minutes: 5 },
  { department: "Dermatology", minutes: 6 },
  { department: "Dermatology", minutes: 6 },
  { department: "Dermatology", minutes: 7 },
  { department: "Dermatology", minutes: 8 },
  { department: "Dermatology", minutes: 9 },
  { department: "Dermatology", minutes: 9 },
  { department: "Dermatology", minutes: 10 },
  { department: "Dermatology", minutes: 11 },
  { department: "Dermatology", minutes: 12 },
  { department: "Dermatology", minutes: 13 },
  { department: "Dermatology", minutes: 15 },
  { department: "Dermatology", minutes: 18 },
  { department: "Dermatology", minutes: 35 },
];

<BoxPlot
  data={data}
  value="minutes"
  group="department"
  highlight="Emergency"
  format="{value} min"
  title="The median emergency wait was 44 minutes"
  subtitle="Minutes from arrival to being seen, sampled visits by department"
  note="Illustrative data. Box: middle half of visits; line: median; whiskers: within 1.5 × IQR; dots: outliers."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "box-plot",
  "data": [
    { "department": "Emergency", "minutes": 12 },
    { "department": "Emergency", "minutes": 18 },
    { "department": "Emergency", "minutes": 22 },
    { "department": "Emergency", "minutes": 25 },
    { "department": "Emergency", "minutes": 27 },
    { "department": "Emergency", "minutes": 31 },
    { "department": "Emergency", "minutes": 34 },
    { "department": "Emergency", "minutes": 38 },
    { "department": "Emergency", "minutes": 41 },
    { "department": "Emergency", "minutes": 44 },
    { "department": "Emergency", "minutes": 47 },
    { "department": "Emergency", "minutes": 52 },
    { "department": "Emergency", "minutes": 58 },
    { "department": "Emergency", "minutes": 63 },
    { "department": "Emergency", "minutes": 71 },
    { "department": "Emergency", "minutes": 84 },
    { "department": "Emergency", "minutes": 96 },
    { "department": "Emergency", "minutes": 131 },
    { "department": "Emergency", "minutes": 188 },
    { "department": "Orthopaedics", "minutes": 9 },
    { "department": "Orthopaedics", "minutes": 11 },
    { "department": "Orthopaedics", "minutes": 14 },
    { "department": "Orthopaedics", "minutes": 15 },
    { "department": "Orthopaedics", "minutes": 17 },
    { "department": "Orthopaedics", "minutes": 19 },
    { "department": "Orthopaedics", "minutes": 20 },
    { "department": "Orthopaedics", "minutes": 22 },
    { "department": "Orthopaedics", "minutes": 24 },
    { "department": "Orthopaedics", "minutes": 25 },
    { "department": "Orthopaedics", "minutes": 27 },
    { "department": "Orthopaedics", "minutes": 29 },
    { "department": "Orthopaedics", "minutes": 31 },
    { "department": "Orthopaedics", "minutes": 34 },
    { "department": "Orthopaedics", "minutes": 38 },
    { "department": "Orthopaedics", "minutes": 43 },
    { "department": "Orthopaedics", "minutes": 55 },
    { "department": "Cardiology", "minutes": 6 },
    { "department": "Cardiology", "minutes": 8 },
    { "department": "Cardiology", "minutes": 9 },
    { "department": "Cardiology", "minutes": 11 },
    { "department": "Cardiology", "minutes": 12 },
    { "department": "Cardiology", "minutes": 13 },
    { "department": "Cardiology", "minutes": 15 },
    { "department": "Cardiology", "minutes": 16 },
    { "department": "Cardiology", "minutes": 17 },
    { "department": "Cardiology", "minutes": 18 },
    { "department": "Cardiology", "minutes": 20 },
    { "department": "Cardiology", "minutes": 21 },
    { "department": "Cardiology", "minutes": 23 },
    { "department": "Cardiology", "minutes": 26 },
    { "department": "Cardiology", "minutes": 28 },
    { "department": "Cardiology", "minutes": 33 },
    { "department": "Cardiology", "minutes": 61 },
    { "department": "Paediatrics", "minutes": 4 },
    { "department": "Paediatrics", "minutes": 5 },
    { "department": "Paediatrics", "minutes": 7 },
    { "department": "Paediatrics", "minutes": 8 },
    { "department": "Paediatrics", "minutes": 9 },
    { "department": "Paediatrics", "minutes": 10 },
    { "department": "Paediatrics", "minutes": 11 },
    { "department": "Paediatrics", "minutes": 12 },
    { "department": "Paediatrics", "minutes": 12 },
    { "department": "Paediatrics", "minutes": 13 },
    { "department": "Paediatrics", "minutes": 14 },
    { "department": "Paediatrics", "minutes": 16 },
    { "department": "Paediatrics", "minutes": 17 },
    { "department": "Paediatrics", "minutes": 19 },
    { "department": "Paediatrics", "minutes": 22 },
    { "department": "Paediatrics", "minutes": 24 },
    { "department": "Dermatology", "minutes": 3 },
    { "department": "Dermatology", "minutes": 4 },
    { "department": "Dermatology", "minutes": 5 },
    { "department": "Dermatology", "minutes": 6 },
    { "department": "Dermatology", "minutes": 6 },
    { "department": "Dermatology", "minutes": 7 },
    { "department": "Dermatology", "minutes": 8 },
    { "department": "Dermatology", "minutes": 9 },
    { "department": "Dermatology", "minutes": 9 },
    { "department": "Dermatology", "minutes": 10 },
    { "department": "Dermatology", "minutes": 11 },
    { "department": "Dermatology", "minutes": 12 },
    { "department": "Dermatology", "minutes": 13 },
    { "department": "Dermatology", "minutes": 15 },
    { "department": "Dermatology", "minutes": 18 },
    { "department": "Dermatology", "minutes": 35 }
  ],
  "value": "minutes",
  "group": "department",
  "highlight": "Emergency",
  "format": "{value} min",
  "title": "The median emergency wait was 44 minutes",
  "subtitle": "Minutes from arrival to being seen, sampled visits by department",
  "note": "Illustrative data. Box: middle half of visits; line: median; whiskers: within 1.5 × IQR; dots: outliers."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `string` |  | Numeric field to summarise. Pass raw rows; quartiles are computed in the chart. |
| `group` | `string` |  | Category field: one box per distinct value. Omit for a single box. |
| `label` | `string` |  | Field naming each row, shown when hovering an outlier. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Horizontal leaves room for long names; vertical suits ordered categories. |
| `whiskers` | `"tukey" \| "minmax"` | `"tukey"` | `tukey`: furthest point within 1.5 × IQR, the rest drawn as outliers. `minmax`: the extremes. |
| `sort` | `"none" \| "asc" \| "desc"` | `"none"` | Order boxes by median. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Sorted, long labels, many outliers

```tsx
import { BoxPlot } from "insightcharts";

const data = [
  { parcel: "Northwind-1000", carrier: "Northwind Express Parcel Service", days: 2.4 },
  { parcel: "Northwind-1001", carrier: "Northwind Express Parcel Service", days: 1.8 },
  { parcel: "Northwind-1002", carrier: "Northwind Express Parcel Service", days: 2.2 },
  { parcel: "Northwind-1003", carrier: "Northwind Express Parcel Service", days: 3.1 },
  { parcel: "Northwind-1004", carrier: "Northwind Express Parcel Service", days: 4 },
  { parcel: "Northwind-1005", carrier: "Northwind Express Parcel Service", days: 2.4 },
  { parcel: "Northwind-1006", carrier: "Northwind Express Parcel Service", days: 2.4 },
  { parcel: "Northwind-1007", carrier: "Northwind Express Parcel Service", days: 1.1 },
  // ... 1072 more rows
];

<BoxPlot
  data={data}
  value="days"
  group="carrier"
  label="parcel"
  sort="asc"
  format="{value}d"
  title="Delivery time by carrier, 180 parcels each"
  subtitle="Days from dispatch to delivery"
  note="Illustrative data"
/>
```

#### Vertical, ordered categories

```tsx
import { BoxPlot } from "insightcharts";

const data = [
  { month: "Jan", temp: 4.8 },
  { month: "Jan", temp: 7.4 },
  { month: "Jan", temp: 0.4 },
  { month: "Jan", temp: 3.5 },
  { month: "Jan", temp: -0.7 },
  { month: "Jan", temp: 2 },
  { month: "Jan", temp: -1.4 },
  { month: "Jan", temp: 7.2 },
  // ... 352 more rows
];

<BoxPlot
  data={data}
  value="temp"
  group="month"
  orientation="vertical"
  highlight={["Jul", "Aug"]}
  format="{value}°"
  title="Daily mean temperature by month"
  subtitle="°C, 30 readings per month. July and August are highlighted."
  note="Illustrative data"
/>
```

#### Single box, min-max whiskers

```tsx
import { BoxPlot } from "insightcharts";

const data = [
  { parcel: "Swift-1000", carrier: "Swift", days: 1.9 },
  { parcel: "Swift-1001", carrier: "Swift", days: 1.2 },
  { parcel: "Swift-1002", carrier: "Swift", days: 1.3 },
  { parcel: "Swift-1003", carrier: "Swift", days: 1.3 },
  { parcel: "Swift-1004", carrier: "Swift", days: 1.1 },
  { parcel: "Swift-1005", carrier: "Swift", days: 0.9 },
  { parcel: "Swift-1006", carrier: "Swift", days: 1.5 },
  { parcel: "Swift-1007", carrier: "Swift", days: 1.7 },
  // ... 172 more rows
];

<BoxPlot
  data={data}
  value="days"
  whiskers="minmax"
  format="{value}d"
  height={120}
  title="Swift delivery times, 180 parcels"
  subtitle="Days from dispatch to delivery, minimum to maximum"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/box-plot.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/box-plot.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Bubble network (`bubble-network`)

> Draws a small set of circles sized by value and joined by thin lines, with one circle highlighted and tagged.

- Component: `BubbleNetwork` (import from `insightcharts`)
- Spec type: `"bubble-network"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Showing which of up to about 12 named things are connected, and how big each is: trade blocs, route maps between hubs, partnerships, shared ownership. Give `x` and `y` to place the circles by hand, for example roughly geographically.

### Avoid

Flows with magnitudes between stages (use sankey-chart); more than about 12 circles or a dense web of links (use heatmap as a matrix, or data-table); comparison of the sizes alone (use bar-chart or circle-pack).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/bubble-network
```

The file lands at `components/insightcharts/atoms/bubble-network.tsx`. `@insightcharts/bubble-network-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BubbleNetwork } from "insightcharts";

const data = [
  { airport: "Lisbon", m: 34 },
  { airport: "Madrid", m: 60 },
  { airport: "Paris", m: 67 },
  { airport: "Frankfurt", m: 59 },
  { airport: "Rome", m: 41 },
  { airport: "Athens", m: 28 },
  { airport: "Istanbul", m: 76 },
];

<BubbleNetwork
  data={data}
  name="airport"
  value="m"
  links={[
    { from: "Istanbul", to: "Frankfurt" },
    { from: "Istanbul", to: "Paris" },
    { from: "Istanbul", to: "Rome" },
    { from: "Istanbul", to: "Athens" },
    { from: "Istanbul", to: "Madrid" },
    { from: "Istanbul", to: "Lisbon" },
    { from: "Madrid", to: "Lisbon" },
    { from: "Paris", to: "Frankfurt" },
    { from: "Rome", to: "Athens" },
  ]}
  highlight="Istanbul"
  tag="Busiest"
  format="{value}m"
  title="Istanbul handled 76 million passengers in 2023"
  subtitle="Passengers at seven airports, millions, 2023. Lines show the routes in this example."
  note="Rounded passenger figures; the routes drawn are illustrative"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "bubble-network",
  "data": [
    { "airport": "Lisbon", "m": 34 },
    { "airport": "Madrid", "m": 60 },
    { "airport": "Paris", "m": 67 },
    { "airport": "Frankfurt", "m": 59 },
    { "airport": "Rome", "m": 41 },
    { "airport": "Athens", "m": 28 },
    { "airport": "Istanbul", "m": 76 }
  ],
  "name": "airport",
  "value": "m",
  "links": [
    { "from": "Istanbul", "to": "Frankfurt" },
    { "from": "Istanbul", "to": "Paris" },
    { "from": "Istanbul", "to": "Rome" },
    { "from": "Istanbul", "to": "Athens" },
    { "from": "Istanbul", "to": "Madrid" },
    { "from": "Istanbul", "to": "Lisbon" },
    { "from": "Madrid", "to": "Lisbon" },
    { "from": "Paris", "to": "Frankfurt" },
    { "from": "Rome", "to": "Athens" }
  ],
  "highlight": "Istanbul",
  "tag": "Busiest",
  "format": "{value}m",
  "title": "Istanbul handled 76 million passengers in 2023",
  "subtitle": "Passengers at seven airports, millions, 2023. Lines show the routes in this example.",
  "note": "Rounded passenger figures; the routes drawn are illustrative"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Name field: one circle per row. |
| `value` (required) | `string` |  | Value field: circle area. |
| `x` | `string` |  | Horizontal position field, 0 (left) to 100 (right). With `y`, places the circles by hand. |
| `y` | `string` |  | Vertical position field, 0 (top) to 100 (bottom). |
| `links` | `{ from: string; to: string; value?: number }[]` |  | Lines between circles, by name. `value` sets the line width and is printed on the line. |
| `tag` | `string` |  | Short tag attached to the highlighted circle, e.g. "Joined 2024". |
| `linkFormat` | `FormatSpec` |  | How to print link values. |
| `linkLabels` | `boolean` |  | Print link values on the lines. Default: on when any link has a value. |
| `layout` | `"ring" \| "hub"` |  | Without `x` and `y`: "ring" spaces the circles round an ellipse in data order, "hub" also moves the most-connected circle to the middle. Default: "hub" when one circle links to most of the others. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md), [network-poster](https://insightcharts.dev/llms/network-poster.md)

### More examples

#### Placed by hand, link values, click to select

```tsx
import { BubbleNetwork } from "insightcharts";

const data = [
  { depot: "Northgate", vans: 120, x: 22, y: 12 },
  { depot: "Riverside", vans: 310, x: 50, y: 46 },
  { depot: "Eastfield", vans: 85, x: 88, y: 30 },
  { depot: "Southwell", vans: 160, x: 62, y: 92 },
  { depot: "Westmere", vans: 44, x: 8, y: 70 },
  { depot: "Airport", vans: 205, x: 86, y: 78 },
];

<BubbleNetwork
  data={data}
  name="depot"
  value="vans"
  x="x"
  y="y"
  links={[
    { from: "Riverside", to: "Northgate", value: 42 },
    { from: "Riverside", to: "Eastfield", value: 18 },
    { from: "Riverside", to: "Southwell", value: 55 },
    { from: "Riverside", to: "Westmere", value: 9 },
    { from: "Riverside", to: "Airport", value: 71 },
    { from: "Southwell", to: "Airport", value: 26 },
  ]}
  highlight="Riverside"
  tag="Main depot"
  select
  linkFormat="{value} trips"
  title="Riverside runs 310 of the fleet's 924 vans"
  subtitle="Vans based at each depot (area) and daily transfer trips between depots (line width)"
  note="Illustrative figures for an invented courier"
/>
```

#### Ring layout, no hub

```tsx
import { BubbleNetwork } from "insightcharts";

const data = [
  { course: "Algebra", students: 48 },
  { course: "Geometry", students: 31 },
  { course: "Statistics", students: 64 },
  { course: "Calculus", students: 22 },
  { course: "Logic", students: 12 },
  { course: "Number theory", students: 9 },
  { course: "Probability", students: 37 },
  { course: "Topology", students: 5 },
];

<BubbleNetwork
  data={data}
  name="course"
  value="students"
  layout="ring"
  links={[
    { from: "Algebra", to: "Geometry" },
    { from: "Algebra", to: "Calculus" },
    { from: "Statistics", to: "Probability" },
    { from: "Calculus", to: "Topology" },
    { from: "Logic", to: "Number theory" },
    { from: "Algebra", to: "Number theory" },
    { from: "Probability", to: "Calculus" },
    { from: "Geometry", to: "Topology" },
  ]}
  title="Statistics has 64 students"
  subtitle="Students enrolled in eight maths courses. Lines join courses where one is required for the other."
  note="Illustrative figures"
/>
```

#### Stress: 12 circles, long names, values from 1 to 480

```tsx
import { BubbleNetwork } from "insightcharts";

const data = [
  { member: "Central Co-operative Wholesale Society", m: 480 },
  { member: "Dairy", m: 210 },
  { member: "Northern Grain and Seed Merchants", m: 96 },
  { member: "Bakery", m: 150 },
  { member: "Orchards", m: 33 },
  { member: "Fishery", m: 61 },
  { member: "Upland Sheep Farmers' Association", m: 18 },
  { member: "Brewery", m: 74 },
  // ... 4 more rows
];

<BubbleNetwork
  data={data}
  name="member"
  value="m"
  format="£{value}m"
  highlight="Central Co-operative Wholesale Society"
  tag="Buys from all eleven"
  links={[
    { from: "Central Co-operative Wholesale Society", to: "Dairy" },
    { from: "Central Co-operative Wholesale Society", to: "Northern Grain and Seed Merchants" },
    { from: "Central Co-operative Wholesale Society", to: "Bakery" },
    { from: "Central Co-operative Wholesale Society", to: "Orchards" },
    { from: "Central Co-operative Wholesale Society", to: "Fishery" },
    { from: "Central Co-operative Wholesale Society", to: "Upland Sheep Farmers' Association" },
    { from: "Central Co-operative Wholesale Society", to: "Brewery" },
    { from: "Central Co-operative Wholesale Society", to: "Market garden" },
    { from: "Central Co-operative Wholesale Society", to: "Apiary" },
    { from: "Central Co-operative Wholesale Society", to: "Mill" },
    { from: "Central Co-operative Wholesale Society", to: "Smokehouse" },
    { from: "Mill", to: "Bakery" },
    { from: "Northern Grain and Seed Merchants", to: "Mill" },
    { from: "Northern Grain and Seed Merchants", to: "Brewery" },
    { from: "Fishery", to: "Smokehouse" },
  ]}
  height={560}
  title="The wholesale society turns over £480 million a year"
  subtitle="Annual turnover of 12 co-operative members, £ million. Lines show who supplies whom."
  note="Illustrative figures for an invented co-operative"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/bubble-network.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/bubble-network.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Bubble scale (`bubble-scale`)

> Places circles sized by one measure along a single value scale set by another, spread sideways so none overlap, with boxed scale marks instead of an axis.

- Component: `BubbleScale` (import from `insightcharts`)
- Spec type: `"bubble-scale"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A poster answer to "where does each one sit on this scale, and how big is it": 5 to about 40 named things with a rate or score (the scale) and a magnitude (the area), such as import dependency against share of demand.

### Avoid

Two measures that should be read against each other on two axes (use scatter-chart); one measure only (use beeswarm-chart or strip-plot); precise comparison of the sizes (use bar-chart); more than about 60 rows (use beeswarm-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/bubble-scale
```

The file lands at `components/insightcharts/atoms/bubble-scale.tsx`. `@insightcharts/bubble-scale-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BubbleScale } from "insightcharts";

const data = [
  { material: "Lithium", imported: 100, kt: 38 },
  { material: "Cobalt", imported: 86, kt: 21 },
  { material: "Graphite", imported: 98, kt: 96 },
  { material: "Nickel", imported: 71, kt: 164 },
  { material: "Manganese", imported: 96, kt: 52 },
  { material: "Copper", imported: 48, kt: 410 },
  { material: "Aluminium", imported: 59, kt: 290 },
  { material: "Rare earths", imported: 100, kt: 9 },
  { material: "Silicon metal", imported: 64, kt: 73 },
  { material: "Zinc", imported: 22, kt: 118 },
  { material: "Steel scrap", imported: 4, kt: 520 },
  { material: "Tin", imported: 78, kt: 14 },
];

<BubbleScale
  data={data}
  name="material"
  value="imported"
  size="kt"
  format="{value}%"
  sizeFormat="{value} kt"
  domain={[0, 100]}
  ticks={[0, 20, 40, 60, 80, 100]}
  scaleLabel="Imported"
  title="Imports supply between 4% and 100% of the region's demand for 12 materials"
  subtitle="Share of each material imported (position) and annual demand in thousand tonnes (area), 12 battery and grid materials"
  note="Illustrative figures for an invented region"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "bubble-scale",
  "data": [
    { "material": "Lithium", "imported": 100, "kt": 38 },
    { "material": "Cobalt", "imported": 86, "kt": 21 },
    { "material": "Graphite", "imported": 98, "kt": 96 },
    { "material": "Nickel", "imported": 71, "kt": 164 },
    { "material": "Manganese", "imported": 96, "kt": 52 },
    { "material": "Copper", "imported": 48, "kt": 410 },
    { "material": "Aluminium", "imported": 59, "kt": 290 },
    { "material": "Rare earths", "imported": 100, "kt": 9 },
    { "material": "Silicon metal", "imported": 64, "kt": 73 },
    { "material": "Zinc", "imported": 22, "kt": 118 },
    { "material": "Steel scrap", "imported": 4, "kt": 520 },
    { "material": "Tin", "imported": 78, "kt": 14 }
  ],
  "name": "material",
  "value": "imported",
  "size": "kt",
  "format": "{value}%",
  "sizeFormat": "{value} kt",
  "domain": [0, 100],
  "ticks": [0, 20, 40, 60, 80, 100],
  "scaleLabel": "Imported",
  "title": "Imports supply between 4% and 100% of the region's demand for 12 materials",
  "subtitle": "Share of each material imported (position) and annual demand in thousand tonnes (area), 12 battery and grid materials",
  "note": "Illustrative figures for an invented region"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Name field: one circle per row. |
| `value` (required) | `string` |  | Numeric field that positions each circle along the scale. Printed with `format`. |
| `size` (required) | `string` |  | Numeric field for circle area. Printed inside or beside each circle with `sizeFormat`. |
| `series` | `string` |  | Field that colours circles by category. Default: circles are shaded along the scale with the sequential ramp. |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Direction of the scale. Narrow containers always use vertical. |
| `domain` | `[number, number]` |  | Scale range. Default: the data extent rounded out to the tick step. |
| `ticks` | `number[]` |  | Values to mark on the scale. Default: about five round values. |
| `scaleLabel` | `string` |  | Short name of the scale measure, printed at the head of the scale. |
| `sizeFormat` | `FormatSpec` |  | How to print the size measure. |
| `guides` | `boolean` | `true` | Thin dotted guide line at each scale mark. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [flow-poster](https://insightcharts.dev/llms/flow-poster.md)

### More examples

#### Colour by series, horizontal

```tsx
import { BubbleScale } from "insightcharts";

const data = [
  { district: "Harbourside", ring: "Inner", carFree: 71, thousand: 18 },
  { district: "Old Town", ring: "Inner", carFree: 64, thousand: 31 },
  { district: "Canal Quarter", ring: "Inner", carFree: 58, thousand: 22 },
  { district: "Station Fields", ring: "Inner", carFree: 49, thousand: 12 },
  { district: "Marketgate", ring: "Inner", carFree: 44, thousand: 27 },
  { district: "Northmoor", ring: "Outer", carFree: 37, thousand: 46 },
  { district: "Eastcliff", ring: "Outer", carFree: 33, thousand: 39 },
  { district: "Larkhill", ring: "Outer", carFree: 29, thousand: 52 },
  // ... 9 more rows
];

<BubbleScale
  data={data}
  name="district"
  value="carFree"
  size="thousand"
  series="ring"
  orientation="horizontal"
  format="{value}%"
  sizeFormat="{value}k"
  scaleLabel="Households without a car"
  title="71% of Harbourside households have no car"
  subtitle="Share of households without a car (position) and population in thousands (area), 17 districts"
  note="Illustrative figures for an invented city"
/>
```

#### Highlight one circle, click to select

```tsx
import { BubbleScale } from "insightcharts";

const data = [
  { district: "Harbourside", ring: "Inner", carFree: 71, thousand: 18 },
  { district: "Old Town", ring: "Inner", carFree: 64, thousand: 31 },
  { district: "Canal Quarter", ring: "Inner", carFree: 58, thousand: 22 },
  { district: "Station Fields", ring: "Inner", carFree: 49, thousand: 12 },
  { district: "Marketgate", ring: "Inner", carFree: 44, thousand: 27 },
  { district: "Northmoor", ring: "Outer", carFree: 37, thousand: 46 },
  { district: "Eastcliff", ring: "Outer", carFree: 33, thousand: 39 },
  { district: "Larkhill", ring: "Outer", carFree: 29, thousand: 52 },
  // ... 9 more rows
];

<BubbleScale
  data={data}
  name="district"
  value="carFree"
  size="thousand"
  highlight="Fenside"
  select
  format="{value}%"
  sizeFormat="{value}k"
  scaleLabel="Without a car"
  title="22% of Fenside's households have no car"
  subtitle="Share of households without a car (position) and population in thousands (area), 17 districts"
  note="Illustrative figures for an invented city"
/>
```

#### Stress: 40 circles crowded at one end, sizes from 1 to 900

```tsx
import { BubbleScale } from "insightcharts";

const data = [
  { fund: "Fund A", fee: 1.15, bn: 900 },
  { fund: "Fund B", fee: 0.22, bn: 413 },
  { fund: "Fund C", fee: 0.11, bn: 226 },
  { fund: "Fund D", fee: 0.28, bn: 139 },
  { fund: "Fund E", fee: 0.17, bn: 87 },
  { fund: "Fund F", fee: 0.66, bn: 48 },
  { fund: "Fund G", fee: 0.23, bn: 33 },
  { fund: "Fund H", fee: 0.12, bn: 24 },
  // ... 32 more rows
];

<BubbleScale
  data={data}
  name="fund"
  value="fee"
  size="bn"
  format="{value}%"
  sizeFormat="${value}bn"
  scaleLabel="Annual fee"
  title="40 funds charge between 0.05% and 2.01% a year"
  subtitle="Annual fee (position) and assets in $ billion (area), 40 index and active funds"
  note="Illustrative figures for invented funds"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/bubble-scale.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/bubble-scale.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Bullet chart (`bullet-chart`)

> Compares one measure per row with its target, optionally against qualitative bands such as poor / fair / good.

- Component: `BulletChart` (import from `insightcharts`)
- Spec type: `"bullet-chart"`
- Level: atom. Category: comparison.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Progress against a target or budget for one to about 10 measures, including measures in different units (`scale: "independent"`); a compact scorecard instead of a row of gauges.

### Avoid

No target or thresholds to compare with (use bar-chart); a single share of a whole (use progress-meter); change over time (use line-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/bullet-chart
```

The file lands at `components/insightcharts/atoms/bullet-chart.tsx`. `@insightcharts/bullet-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BulletChart } from "insightcharts";

const data = [
  { region: "North America", sales: 94, target: 80 },
  { region: "Europe", sales: 71, target: 85 },
  { region: "Asia Pacific", sales: 63, target: 60 },
  { region: "Latin America", sales: 38, target: 55 },
];

<BulletChart
  data={data}
  category="region"
  value="sales"
  target="target"
  bands={[50, 75, 110]}
  bandNames={["Below plan", "On plan", "Stretch"]}
  names={{ sales: "Sales", target: "Target" }}
  format="currency:USD"
  height={240}
  title="Europe sold $71 million against a target of $85 million in 2024"
  subtitle="Sales against target by region, $ millions, 2024"
  source="Company accounts"
  note="Illustrative figures."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "bullet-chart",
  "data": [
    { "region": "North America", "sales": 94, "target": 80 },
    { "region": "Europe", "sales": 71, "target": 85 },
    { "region": "Asia Pacific", "sales": 63, "target": 60 },
    { "region": "Latin America", "sales": 38, "target": 55 }
  ],
  "category": "region",
  "value": "sales",
  "target": "target",
  "bands": [50, 75, 110],
  "bandNames": ["Below plan", "On plan", "Stretch"],
  "names": { "sales": "Sales", "target": "Target" },
  "format": "currency:USD",
  "height": 240,
  "title": "Europe sold $71 million against a target of $85 million in 2024",
  "subtitle": "Sales against target by region, $ millions, 2024",
  "source": "Company accounts",
  "note": "Illustrative figures."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `category` (required) | `string` |  | Field naming each row. |
| `value` (required) | `string` |  | Field with the measured value. Values below zero are not supported. |
| `target` | `string` |  | Field with the target, drawn as a tick across the bar. |
| `bands` | `number[] \| string[]` |  | Ascending upper bounds of qualitative bands, or the fields holding them per row. Omit unless the thresholds are real. |
| `bandNames` | `string[]` |  | Band names, lowest first, for the legend and tooltip. |
| `max` | `number \| string` |  | End of the scale: a number or a per-row field. Default: just past the largest value, target or band. |
| `scale` | `"shared" \| "independent"` | `"shared"` | One axis for all rows, or each row on its own scale (different units). |
| `formatField` | `string` |  | Field holding a format spec per row, for mixed units. |
| `names` | `Record<string, string>` |  | Display names for the value and target fields. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Scorecard with a separate scale per row

```tsx
import { BulletChart } from "insightcharts";

const data = [
  { kpi: "Revenue", actual: 4.6, goal: 5, low: 3.5, mid: 4.5, high: 6, unit: "${value}m" },
  { kpi: "Gross margin", actual: 41, goal: 38, low: 25, mid: 35, high: 50, unit: "{value}%" },
  {
    kpi: "New customers",
    actual: 1320,
    goal: 1500,
    low: 900,
    mid: 1300,
    high: 1800,
    unit: "integer",
  },
  {
    kpi: "Customer satisfaction",
    actual: 4.4,
    goal: 4.5,
    low: 3.5,
    mid: 4.2,
    high: 5,
    unit: "decimal:1",
  },
  {
    kpi: "Average order value",
    actual: 58,
    goal: 52,
    low: 40,
    mid: 50,
    high: 65,
    unit: "currency:EUR",
  },
];

<BulletChart
  data={data}
  category="kpi"
  value="actual"
  target="goal"
  bands={["low", "mid", "high"]}
  bandNames={["Poor", "Acceptable", "Good"]}
  scale="independent"
  formatField="unit"
  names={{ actual: "Actual", goal: "Target" }}
  height={300}
  title="Third-quarter revenue was $4.6 million against a target of $5.0 million"
  subtitle="Third-quarter results against target"
  note="Illustrative figures."
/>
```

#### No thresholds, one row highlighted

```tsx
import { BulletChart } from "insightcharts";

const data = [
  { team: "Payments", done: 86, plan: 80 },
  { team: "Search", done: 74, plan: 80 },
  { team: "Onboarding", done: 52, plan: 80 },
  { team: "Mobile", done: 91, plan: 80 },
  { team: "Data platform", done: 79, plan: 80 },
];

<BulletChart
  data={data}
  category="team"
  value="done"
  target="plan"
  highlight="Onboarding"
  names={{ done: "Delivered", plan: "Committed" }}
  format="{value}%"
  height={260}
  title="Onboarding delivered 52% of its quarterly roadmap"
  subtitle="Share of quarterly roadmap delivered, by team. The tick marks the 80% commitment."
  note="Illustrative figures."
/>
```

#### Stress: 10 rows with long labels

```tsx
import { BulletChart } from "insightcharts";

const data = [
  { measure: "Percentage of emergency patients seen within four hours", actual: 71, standard: 95 },
  {
    measure: "Ambulance response to life-threatening calls within target",
    actual: 64,
    standard: 90,
  },
  {
    measure: "Cancer patients starting treatment within 62 days of referral",
    actual: 62,
    standard: 85,
  },
  { measure: "Planned operations within 18 weeks", actual: 58, standard: 92 },
  { measure: "Diagnostic tests within six weeks", actual: 76, standard: 99 },
  { measure: "GP appointments within two weeks", actual: 83, standard: 85 },
  { measure: "Mental health referrals seen within four weeks", actual: 69, standard: 75 },
  { measure: "Beds occupied by patients fit for discharge (inverted)", actual: 88, standard: 95 },
  // ... 2 more rows
];

<BulletChart
  data={data}
  category="measure"
  value="actual"
  target="standard"
  max={100}
  names={{ actual: "Performance", standard: "Standard" }}
  format="{value}%"
  height={440}
  title="The health service missed all 10 national standards in the latest month"
  subtitle="Performance against the national standard, % of cases"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/bullet-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/bullet-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Bump chart (`bump-chart`)

> Shows how the ranking of entities changes over time, with rank 1 at the top and each line named at its end.

- Component: `BumpChart` (import from `insightcharts`)
- Spec type: `"bump-chart"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

League tables over 3 to about 15 periods for up to about 12 entities, when the order and the changes in rank are what matter and the underlying values differ too much (or too little) to share an axis.

### Avoid

When the size of the values matters (use line-chart); only two periods (use slope-chart); a single ranking (use bar-chart or lollipop-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/bump-chart
```

The file lands at `components/insightcharts/atoms/bump-chart.tsx`. `@insightcharts/bump-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BumpChart } from "insightcharts";

const data = [
  { year: "2019", Tesla: 0.37, BYD: 0.23, SAIC: 0.16, Volkswagen: 0.14, Hyundai: 0.13, Geely: 0.12 },
  { year: "2020", Tesla: 0.5, BYD: 0.18, SAIC: 0.27, Volkswagen: 0.42, Hyundai: 0.2, Geely: 0.1 },
  { year: "2021", Tesla: 0.94, BYD: 0.6, SAIC: 0.68, Volkswagen: 0.76, Hyundai: 0.35, Geely: 0.2 },
  { year: "2022", Tesla: 1.31, BYD: 1.86, SAIC: 0.72, Volkswagen: 0.83, Hyundai: 0.51, Geely: 0.65 },
  { year: "2023", Tesla: 1.81, BYD: 3.02, SAIC: 0.79, Volkswagen: 1, Hyundai: 0.57, Geely: 0.93 },
  { year: "2024", Tesla: 1.79, BYD: 4.27, SAIC: 0.9, Volkswagen: 1.04, Hyundai: 0.56, Geely: 1.39 },
];

<BumpChart
  data={data}
  x="year"
  y={["Tesla", "BYD", "SAIC", "Volkswagen", "Hyundai", "Geely"]}
  highlight="BYD"
  format="{value}m"
  height={300}
  title="BYD rose from fifth in 2020 to first in 2022"
  subtitle="Rank among six carmakers by plug-in vehicles sold worldwide, 2019 to 2024"
  source="Company reports"
  note="Approximate figures."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "bump-chart",
  "data": [
    {
      "year": "2019",
      "Tesla": 0.37,
      "BYD": 0.23,
      "SAIC": 0.16,
      "Volkswagen": 0.14,
      "Hyundai": 0.13,
      "Geely": 0.12
    },
    {
      "year": "2020",
      "Tesla": 0.5,
      "BYD": 0.18,
      "SAIC": 0.27,
      "Volkswagen": 0.42,
      "Hyundai": 0.2,
      "Geely": 0.1
    },
    {
      "year": "2021",
      "Tesla": 0.94,
      "BYD": 0.6,
      "SAIC": 0.68,
      "Volkswagen": 0.76,
      "Hyundai": 0.35,
      "Geely": 0.2
    },
    {
      "year": "2022",
      "Tesla": 1.31,
      "BYD": 1.86,
      "SAIC": 0.72,
      "Volkswagen": 0.83,
      "Hyundai": 0.51,
      "Geely": 0.65
    },
    {
      "year": "2023",
      "Tesla": 1.81,
      "BYD": 3.02,
      "SAIC": 0.79,
      "Volkswagen": 1,
      "Hyundai": 0.57,
      "Geely": 0.93
    },
    {
      "year": "2024",
      "Tesla": 1.79,
      "BYD": 4.27,
      "SAIC": 0.9,
      "Volkswagen": 1.04,
      "Hyundai": 0.56,
      "Geely": 1.39
    }
  ],
  "x": "year",
  "y": ["Tesla", "BYD", "SAIC", "Volkswagen", "Hyundai", "Geely"],
  "highlight": "BYD",
  "format": "{value}m",
  "height": 300,
  "title": "BYD rose from fifth in 2020 to first in 2022",
  "subtitle": "Rank among six carmakers by plug-in vehicles sold worldwide, 2019 to 2024",
  "source": "Company reports",
  "note": "Approximate figures."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Time or ordered category field. |
| `y` (required) | `string \| string[]` |  | Value field to rank by, or several (one line each). |
| `series` | `string` |  | Field that splits rows into entities (long data). |
| `ranked` | `boolean` | `false` | The values are already ranks (1 = best) and are plotted as given. |
| `order` | `"desc" \| "asc"` | `"desc"` | Which values rank first when ranks are computed: largest (`desc`) or smallest (`asc`). |
| `startLabels` | `boolean` |  | Name lines at the start as well as the end. Default: on when the chart is wide enough. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Every line coloured

```tsx
import { BumpChart } from "insightcharts";

const data = [
  { season: "2020", Arsenal: 8, Liverpool: 1, "Manchester City": 2, Chelsea: 4, Tottenham: 6 },
  { season: "2021", Arsenal: 8, Liverpool: 3, "Manchester City": 1, Chelsea: 4, Tottenham: 7 },
  { season: "2022", Arsenal: 5, Liverpool: 2, "Manchester City": 1, Chelsea: 3, Tottenham: 4 },
  { season: "2023", Arsenal: 2, Liverpool: 5, "Manchester City": 1, Chelsea: 12, Tottenham: 8 },
  { season: "2024", Arsenal: 2, Liverpool: 3, "Manchester City": 1, Chelsea: 6, Tottenham: 5 },
];

<BumpChart
  data={data}
  x="season"
  y={["Arsenal", "Liverpool", "Manchester City", "Chelsea", "Tottenham"]}
  ranked
  height={340}
  title="Arsenal rose from eighth in 2020 to second in 2024"
  subtitle="Final Premier League position, seasons ending 2020 to 2024"
  source="Premier League"
  note="Figures are approximate, for illustration"
/>
```

#### Long format with a late entrant

```tsx
import { BumpChart } from "insightcharts";

const data = [
  { year: "2021", language: "Python", share: 30 },
  { year: "2021", language: "JavaScript", share: 34 },
  { year: "2021", language: "Java", share: 22 },
  { year: "2021", language: "Go", share: 6 },
  { year: "2022", language: "Python", share: 33 },
  { year: "2022", language: "JavaScript", share: 32 },
  { year: "2022", language: "Java", share: 20 },
  { year: "2022", language: "Go", share: 8 },
  // ... 11 more rows
];

<BumpChart
  data={data}
  x="year"
  y="share"
  series="language"
  highlight="Rust"
  format="{value}%"
  height={300}
  title="Rust ranked third in 2024 with 14% of new repositories"
  subtitle="Rank by share of new repositories, by primary language"
  note="Illustrative figures."
/>
```

#### Stress: 12 entities over 10 periods

```tsx
import { BumpChart } from "insightcharts";

const data = [
  {
    year: "2015",
    "United States": 100,
    China: 97,
    Japan: 94,
    Germany: 82,
    India: 79,
    "United Kingdom": 67,
    France: 64,
    Italy: 52,
    Brazil: 49,
    Canada: 37,
    "Republic of Korea": 34,
    "Russian Federation": 31,
  },
  {
    year: "2016",
    "United States": 107,
    China: 111,
    Japan: 101,
    Germany: 83,
    India: 92,
    "United Kingdom": 74,
    France: 66,
    Italy: 59,
    Brazil: 55,
    Canada: 48,
    "Republic of Korea": 33,
    "Russian Federation": 34,
  },
  {
    year: "2017",
    "United States": 105,
    China: 128,
    Japan: 109,
    Germany: 93,
    India: 108,
    "United Kingdom": 91,
    France: 68,
    Italy: 57,
    Brazil: 62,
    Canada: 50,
    "Republic of Korea": 32,
    "Russian Federation": 38,
  },
  {
    year: "2018",
    "United States": 103,
    China: 158,
    Japan: 118,
    Germany: 94,
    India: 129,
    "United Kingdom": 101,
    France: 71,
    Italy: 55,
    Brazil: 79,
    Canada: 53,
    "Republic of Korea": 40,
    "Russian Federation": 43,
  },
  {
    year: "2019",
    "United States": 101,
    China: 182,
    Japan: 128,
    Germany: 95,
    India: 162,
    "United Kingdom": 113,
    France: 83,
    Italy: 53,
    Brazil: 90,
    Canada: 56,
    "Republic of Korea": 39,
    "Russian Federation": 49,
  },
  {
    year: "2020",
    "United States": 108,
    China: 211,
    Japan: 149,
    Germany: 96,
    India: 193,
    "United Kingdom": 126,
    France: 86,
    Italy: 51,
    Brazil: 103,
    Canada: 69,
    "Republic of Korea": 39,
    "Russian Federation": 67,
  },
  {
    year: "2021",
    "United States": 106,
    China: 246,
    Japan: 162,
    Germany: 97,
    India: 230,
    "United Kingdom": 151,
    France: 90,
    Italy: 58,
    Brazil: 118,
    Canada: 73,
    "Republic of Korea": 38,
    "Russian Federation": 77,
  },
  {
    year: "2022",
    "United States": 104,
    China: 296,
    Japan: 176,
    Germany: 108,
    India: 275,
    "United Kingdom": 169,
    France: 94,
    Italy: 56,
    Brazil: 136,
    Canada: 78,
    "Republic of Korea": 46,
    "Russian Federation": 90,
  },
  // ... 2 more rows
];

<BumpChart
  data={data}
  x="year"
  y={[
    "United States",
    "China",
    "Japan",
    "Germany",
    "India",
    "United Kingdom",
    "France",
    "Italy",
    "Brazil",
    "Canada",
    "Republic of Korea",
    "Russian Federation",
  ]}
  height={420}
  title="Rank of 12 countries by an illustrative index, 2015 to 2024"
  subtitle="The eight highest-ranked countries in 2024 are coloured"
  note="Synthetic data for layout testing."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/bump-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/bump-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Calendar heatmap (`calendar-heatmap`)

> Colours every day of one or more years by a value, laid out as a grid of weeks.

- Component: `CalendarHeatmap` (import from `insightcharts`)
- Spec type: `"calendar-heatmap"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Daily data over months or years where weekly rhythm, seasonality, streaks and gaps matter: activity, sales, incidents, habits.

### Avoid

Reading the trend or exact values (use line-chart); fewer than about three months of days (use bar-chart); a non-daily grain such as hour by weekday (use heatmap).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/calendar-heatmap
```

The file lands at `components/insightcharts/atoms/calendar-heatmap.tsx`. `@insightcharts/calendar-heatmap-demo` adds a ready-made example next to it.

### Usage

```tsx
import { CalendarHeatmap } from "insightcharts";

const data = [
  { date: "2024-01-01", commits: 16 },
  { date: "2024-01-02", commits: 9 },
  { date: "2024-01-03", commits: 8 },
  { date: "2024-01-04", commits: 6 },
  { date: "2024-01-05", commits: 8 },
  { date: "2024-01-06", commits: 1 },
  { date: "2024-01-07", commits: 1 },
  { date: "2024-01-08", commits: 17 },
  { date: "2024-01-09", commits: 12 },
  { date: "2024-01-10", commits: 13 },
  { date: "2024-01-11", commits: 14 },
  { date: "2024-01-12", commits: 9 },
  { date: "2024-01-13", commits: 2 },
  { date: "2024-01-14", commits: 2 },
  { date: "2024-01-15", commits: 11 },
  { date: "2024-01-16", commits: 14 },
  { date: "2024-01-17", commits: 10 },
  { date: "2024-01-18", commits: 11 },
  { date: "2024-01-19", commits: 14 },
  { date: "2024-01-20", commits: 2 },
  { date: "2024-01-21", commits: 2 },
  { date: "2024-01-22", commits: 11 },
  { date: "2024-01-23", commits: 9 },
  { date: "2024-01-24", commits: 14 },
  { date: "2024-01-25", commits: 8 },
  { date: "2024-01-26", commits: 14 },
  { date: "2024-01-27", commits: 1 },
  { date: "2024-01-28", commits: 1 },
  { date: "2024-01-29", commits: 10 },
  { date: "2024-01-30", commits: 5 },
  { date: "2024-01-31", commits: 11 },
  { date: "2024-02-01", commits: 12 },
  { date: "2024-02-02", commits: 15 },
  { date: "2024-02-03", commits: 1 },
  { date: "2024-02-04", commits: 2 },
  { date: "2024-02-05", commits: 10 },
  { date: "2024-02-06", commits: 9 },
  { date: "2024-02-07", commits: 12 },
  { date: "2024-02-08", commits: 6 },
  { date: "2024-02-09", commits: 13 },
  { date: "2024-02-10", commits: 1 },
  { date: "2024-02-11", commits: 1 },
  { date: "2024-02-12", commits: 7 },
  { date: "2024-02-13", commits: 17 },
  { date: "2024-02-14", commits: 16 },
  { date: "2024-02-15", commits: 17 },
  { date: "2024-02-16", commits: 10 },
  { date: "2024-02-17", commits: 1 },
  { date: "2024-02-18", commits: 1 },
  { date: "2024-02-19", commits: 11 },
  { date: "2024-02-20", commits: 6 },
  { date: "2024-02-21", commits: 15 },
  { date: "2024-02-22", commits: 17 },
  { date: "2024-02-23", commits: 5 },
  { date: "2024-02-24", commits: 1 },
  { date: "2024-02-25", commits: 2 },
  { date: "2024-02-26", commits: 14 },
  { date: "2024-02-27", commits: 12 },
  { date: "2024-02-28", commits: 18 },
  { date: "2024-02-29", commits: 9 },
  { date: "2024-03-01", commits: 16 },
  { date: "2024-03-02", commits: 1 },
  { date: "2024-03-03", commits: 1 },
  { date: "2024-03-04", commits: 15 },
  { date: "2024-03-05", commits: 5 },
  { date: "2024-03-06", commits: 9 },
  { date: "2024-03-07", commits: 12 },
  { date: "2024-03-08", commits: 16 },
  { date: "2024-03-09", commits: 2 },
  { date: "2024-03-10", commits: 1 },
  { date: "2024-03-11", commits: 11 },
  { date: "2024-03-12", commits: 14 },
  { date: "2024-03-13", commits: 18 },
  { date: "2024-03-14", commits: 14 },
  { date: "2024-03-15", commits: 9 },
  { date: "2024-03-16", commits: 1 },
  { date: "2024-03-17", commits: 2 },
  { date: "2024-03-18", commits: 9 },
  { date: "2024-03-19", commits: 18 },
  { date: "2024-03-20", commits: 16 },
  { date: "2024-03-21", commits: 8 },
  { date: "2024-03-22", commits: 18 },
  { date: "2024-03-23", commits: 1 },
  { date: "2024-03-24", commits: 3 },
  { date: "2024-03-25", commits: 30 },
  { date: "2024-03-26", commits: 19 },
  { date: "2024-03-27", commits: 12 },
  { date: "2024-03-28", commits: 11 },
  { date: "2024-03-29", commits: 9 },
  { date: "2024-03-30", commits: 1 },
  { date: "2024-03-31", commits: 2 },
  { date: "2024-04-01", commits: 7 },
  { date: "2024-04-02", commits: 18 },
  { date: "2024-04-03", commits: 19 },
  { date: "2024-04-04", commits: 15 },
  { date: "2024-04-05", commits: 10 },
  { date: "2024-04-06", commits: 1 },
  { date: "2024-04-07", commits: 1 },
  { date: "2024-04-08", commits: 18 },
  { date: "2024-04-09", commits: 9 },
  { date: "2024-04-10", commits: 14 },
  { date: "2024-04-11", commits: 16 },
  { date: "2024-04-12", commits: 14 },
  { date: "2024-04-13", commits: 2 },
  { date: "2024-04-14", commits: 2 },
  { date: "2024-04-15", commits: 15 },
  { date: "2024-04-16", commits: 7 },
  { date: "2024-04-17", commits: 15 },
  { date: "2024-04-18", commits: 17 },
  { date: "2024-04-19", commits: 8 },
  { date: "2024-04-20", commits: 1 },
  { date: "2024-04-21", commits: 2 },
  { date: "2024-04-22", commits: 11 },
  { date: "2024-04-23", commits: 19 },
  { date: "2024-04-24", commits: 18 },
  { date: "2024-04-25", commits: 6 },
  { date: "2024-04-26", commits: 16 },
  { date: "2024-04-27", commits: 1 },
  { date: "2024-04-28", commits: 2 },
  { date: "2024-04-29", commits: 13 },
  { date: "2024-04-30", commits: 6 },
  { date: "2024-05-01", commits: 16 },
  { date: "2024-05-02", commits: 7 },
  { date: "2024-05-03", commits: 19 },
  { date: "2024-05-04", commits: 1 },
  { date: "2024-05-05", commits: 1 },
  { date: "2024-05-06", commits: 12 },
  { date: "2024-05-07", commits: 17 },
  { date: "2024-05-08", commits: 11 },
  { date: "2024-05-09", commits: 10 },
  { date: "2024-05-10", commits: 19 },
  { date: "2024-05-11", commits: 2 },
  { date: "2024-05-12", commits: 1 },
  { date: "2024-05-13", commits: 7 },
  { date: "2024-05-14", commits: 17 },
  { date: "2024-05-15", commits: 7 },
  { date: "2024-05-16", commits: 18 },
  { date: "2024-05-17", commits: 10 },
  { date: "2024-05-18", commits: 1 },
  { date: "2024-05-19", commits: 1 },
  { date: "2024-05-20", commits: 8 },
  { date: "2024-05-21", commits: 18 },
  { date: "2024-05-22", commits: 12 },
  { date: "2024-05-23", commits: 19 },
  { date: "2024-05-24", commits: 17 },
  { date: "2024-05-25", commits: 2 },
  { date: "2024-05-26", commits: 2 },
  { date: "2024-05-27", commits: 11 },
  { date: "2024-05-28", commits: 13 },
  { date: "2024-05-29", commits: 14 },
  { date: "2024-05-30", commits: 14 },
  { date: "2024-05-31", commits: 12 },
  { date: "2024-06-01", commits: 1 },
  { date: "2024-06-02", commits: 1 },
  { date: "2024-06-03", commits: 15 },
  { date: "2024-06-04", commits: 15 },
  { date: "2024-06-05", commits: 17 },
  { date: "2024-06-06", commits: 8 },
  { date: "2024-06-07", commits: 17 },
  { date: "2024-06-08", commits: 2 },
  { date: "2024-06-09", commits: 1 },
  { date: "2024-06-10", commits: 9 },
  { date: "2024-06-11", commits: 11 },
  { date: "2024-06-12", commits: 16 },
  { date: "2024-06-13", commits: 12 },
  { date: "2024-06-14", commits: 11 },
  { date: "2024-06-15", commits: 1 },
  { date: "2024-06-16", commits: 2 },
  { date: "2024-06-17", commits: 13 },
  { date: "2024-06-18", commits: 16 },
  { date: "2024-06-19", commits: 12 },
  { date: "2024-06-20", commits: 18 },
  { date: "2024-06-21", commits: 9 },
  { date: "2024-06-22", commits: 1 },
  { date: "2024-06-23", commits: 2 },
  { date: "2024-06-24", commits: 12 },
  { date: "2024-06-25", commits: 12 },
  { date: "2024-06-26", commits: 14 },
  { date: "2024-06-27", commits: 14 },
  { date: "2024-06-28", commits: 24 },
  { date: "2024-06-29", commits: 2 },
  { date: "2024-06-30", commits: 2 },
  { date: "2024-07-01", commits: 17 },
  { date: "2024-07-02", commits: 9 },
  { date: "2024-07-03", commits: 18 },
  { date: "2024-07-04", commits: 16 },
  { date: "2024-07-05", commits: 7 },
  { date: "2024-07-06", commits: 1 },
  { date: "2024-07-07", commits: 1 },
  { date: "2024-07-08", commits: 21 },
  { date: "2024-07-09", commits: 15 },
  { date: "2024-07-10", commits: 7 },
  { date: "2024-07-11", commits: 9 },
  { date: "2024-07-12", commits: 21 },
  { date: "2024-07-13", commits: 1 },
  { date: "2024-07-14", commits: 2 },
  { date: "2024-07-15", commits: 20 },
  { date: "2024-07-16", commits: 20 },
  { date: "2024-07-17", commits: 16 },
  { date: "2024-07-18", commits: 22 },
  { date: "2024-07-19", commits: 18 },
  { date: "2024-07-20", commits: 2 },
  { date: "2024-07-21", commits: 2 },
  { date: "2024-07-22", commits: 7 },
  { date: "2024-07-23", commits: 20 },
  { date: "2024-07-24", commits: 22 },
  { date: "2024-07-25", commits: 14 },
  { date: "2024-07-26", commits: 18 },
  { date: "2024-07-27", commits: 1 },
  { date: "2024-07-28", commits: 2 },
  { date: "2024-07-29", commits: 9 },
  { date: "2024-07-30", commits: 17 },
  { date: "2024-07-31", commits: 18 },
  { date: "2024-08-01", commits: 17 },
  { date: "2024-08-02", commits: 19 },
  { date: "2024-08-03", commits: 1 },
  { date: "2024-08-04", commits: 1 },
  { date: "2024-08-05", commits: 2 },
  { date: "2024-08-06", commits: 1 },
  { date: "2024-08-07", commits: 1 },
  { date: "2024-08-08", commits: 2 },
  { date: "2024-08-09", commits: 2 },
  { date: "2024-08-12", commits: 2 },
  { date: "2024-08-13", commits: 1 },
  { date: "2024-08-14", commits: 3 },
  { date: "2024-08-15", commits: 2 },
  { date: "2024-08-16", commits: 2 },
  { date: "2024-08-19", commits: 18 },
  { date: "2024-08-20", commits: 15 },
  { date: "2024-08-21", commits: 19 },
  { date: "2024-08-22", commits: 18 },
  { date: "2024-08-23", commits: 7 },
  { date: "2024-08-24", commits: 2 },
  { date: "2024-08-25", commits: 1 },
  { date: "2024-08-26", commits: 12 },
  { date: "2024-08-27", commits: 14 },
  { date: "2024-08-28", commits: 12 },
  { date: "2024-08-29", commits: 11 },
  { date: "2024-08-30", commits: 11 },
  { date: "2024-08-31", commits: 1 },
  { date: "2024-09-01", commits: 1 },
  { date: "2024-09-02", commits: 20 },
  { date: "2024-09-03", commits: 22 },
  { date: "2024-09-04", commits: 11 },
  { date: "2024-09-05", commits: 19 },
  { date: "2024-09-06", commits: 15 },
  { date: "2024-09-07", commits: 2 },
  { date: "2024-09-08", commits: 1 },
  { date: "2024-09-09", commits: 8 },
  { date: "2024-09-10", commits: 22 },
  { date: "2024-09-11", commits: 23 },
  { date: "2024-09-12", commits: 9 },
  { date: "2024-09-13", commits: 19 },
  { date: "2024-09-14", commits: 1 },
  { date: "2024-09-15", commits: 2 },
  { date: "2024-09-16", commits: 11 },
  { date: "2024-09-17", commits: 13 },
  { date: "2024-09-18", commits: 11 },
  { date: "2024-09-19", commits: 12 },
  { date: "2024-09-20", commits: 18 },
  { date: "2024-09-21", commits: 2 },
  { date: "2024-09-22", commits: 1 },
  { date: "2024-09-23", commits: 15 },
  { date: "2024-09-24", commits: 37 },
  { date: "2024-09-25", commits: 38 },
  { date: "2024-09-26", commits: 30 },
  { date: "2024-09-27", commits: 39 },
  { date: "2024-09-28", commits: 2 },
  { date: "2024-09-29", commits: 2 },
  { date: "2024-09-30", commits: 30 },
  { date: "2024-10-01", commits: 22 },
  { date: "2024-10-02", commits: 19 },
  { date: "2024-10-03", commits: 24 },
  { date: "2024-10-04", commits: 19 },
  { date: "2024-10-05", commits: 1 },
  { date: "2024-10-06", commits: 1 },
  { date: "2024-10-07", commits: 23 },
  { date: "2024-10-08", commits: 9 },
  { date: "2024-10-09", commits: 21 },
  { date: "2024-10-10", commits: 14 },
  { date: "2024-10-11", commits: 12 },
  { date: "2024-10-12", commits: 1 },
  { date: "2024-10-13", commits: 1 },
  { date: "2024-10-14", commits: 8 },
  { date: "2024-10-15", commits: 8 },
  { date: "2024-10-16", commits: 21 },
  { date: "2024-10-17", commits: 13 },
  { date: "2024-10-18", commits: 23 },
  { date: "2024-10-19", commits: 1 },
  { date: "2024-10-20", commits: 1 },
  { date: "2024-10-21", commits: 15 },
  { date: "2024-10-22", commits: 17 },
  { date: "2024-10-23", commits: 19 },
  { date: "2024-10-24", commits: 24 },
  { date: "2024-10-25", commits: 19 },
  { date: "2024-10-26", commits: 1 },
  { date: "2024-10-27", commits: 2 },
  { date: "2024-10-28", commits: 16 },
  { date: "2024-10-29", commits: 22 },
  { date: "2024-10-30", commits: 13 },
  { date: "2024-10-31", commits: 23 },
  { date: "2024-11-01", commits: 16 },
  { date: "2024-11-02", commits: 1 },
  { date: "2024-11-03", commits: 2 },
  { date: "2024-11-04", commits: 20 },
  { date: "2024-11-05", commits: 17 },
  { date: "2024-11-06", commits: 13 },
  { date: "2024-11-07", commits: 14 },
  { date: "2024-11-08", commits: 19 },
  { date: "2024-11-09", commits: 1 },
  { date: "2024-11-10", commits: 1 },
  { date: "2024-11-11", commits: 25 },
  { date: "2024-11-12", commits: 8 },
  { date: "2024-11-13", commits: 24 },
  { date: "2024-11-14", commits: 10 },
  { date: "2024-11-15", commits: 15 },
  { date: "2024-11-16", commits: 2 },
  { date: "2024-11-17", commits: 2 },
  { date: "2024-11-18", commits: 11 },
  { date: "2024-11-19", commits: 7 },
  { date: "2024-11-20", commits: 15 },
  { date: "2024-11-21", commits: 22 },
  { date: "2024-11-22", commits: 8 },
  { date: "2024-11-23", commits: 1 },
  { date: "2024-11-24", commits: 2 },
  { date: "2024-11-25", commits: 19 },
  { date: "2024-11-26", commits: 8 },
  { date: "2024-11-27", commits: 17 },
  { date: "2024-11-28", commits: 9 },
  { date: "2024-11-29", commits: 25 },
  { date: "2024-11-30", commits: 1 },
  { date: "2024-12-01", commits: 1 },
  { date: "2024-12-02", commits: 13 },
  { date: "2024-12-03", commits: 12 },
  { date: "2024-12-04", commits: 10 },
  { date: "2024-12-05", commits: 14 },
  { date: "2024-12-06", commits: 8 },
  { date: "2024-12-07", commits: 1 },
  { date: "2024-12-08", commits: 1 },
  { date: "2024-12-09", commits: 16 },
  { date: "2024-12-10", commits: 8 },
  { date: "2024-12-11", commits: 19 },
  { date: "2024-12-12", commits: 23 },
  { date: "2024-12-13", commits: 22 },
  { date: "2024-12-14", commits: 2 },
  { date: "2024-12-15", commits: 2 },
  { date: "2024-12-16", commits: 9 },
  { date: "2024-12-17", commits: 24 },
  { date: "2024-12-18", commits: 21 },
  { date: "2024-12-19", commits: 18 },
  { date: "2024-12-20", commits: 21 },
  { date: "2024-12-21", commits: 1 },
  { date: "2024-12-22", commits: 1 },
  { date: "2024-12-23", commits: 24 },
  { date: "2024-12-24", commits: 37 },
  { date: "2024-12-25", commits: 17 },
  { date: "2024-12-26", commits: 34 },
  { date: "2024-12-27", commits: 24 },
  { date: "2024-12-28", commits: 2 },
  { date: "2024-12-29", commits: 3 },
  { date: "2024-12-30", commits: 24 },
  { date: "2024-12-31", commits: 33 },
];

<CalendarHeatmap
  data={data}
  date="date"
  value="commits"
  title="Commits per day to the main repository, 2024"
  subtitle="Number of commits each day"
  note="Illustrative data. Pale cells are days with no commits."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "calendar-heatmap",
  "data": [
    { "date": "2024-01-01", "commits": 16 },
    { "date": "2024-01-02", "commits": 9 },
    { "date": "2024-01-03", "commits": 8 },
    { "date": "2024-01-04", "commits": 6 },
    { "date": "2024-01-05", "commits": 8 },
    { "date": "2024-01-06", "commits": 1 },
    { "date": "2024-01-07", "commits": 1 },
    { "date": "2024-01-08", "commits": 17 },
    { "date": "2024-01-09", "commits": 12 },
    { "date": "2024-01-10", "commits": 13 },
    { "date": "2024-01-11", "commits": 14 },
    { "date": "2024-01-12", "commits": 9 },
    { "date": "2024-01-13", "commits": 2 },
    { "date": "2024-01-14", "commits": 2 },
    { "date": "2024-01-15", "commits": 11 },
    { "date": "2024-01-16", "commits": 14 },
    { "date": "2024-01-17", "commits": 10 },
    { "date": "2024-01-18", "commits": 11 },
    { "date": "2024-01-19", "commits": 14 },
    { "date": "2024-01-20", "commits": 2 },
    { "date": "2024-01-21", "commits": 2 },
    { "date": "2024-01-22", "commits": 11 },
    { "date": "2024-01-23", "commits": 9 },
    { "date": "2024-01-24", "commits": 14 },
    { "date": "2024-01-25", "commits": 8 },
    { "date": "2024-01-26", "commits": 14 },
    { "date": "2024-01-27", "commits": 1 },
    { "date": "2024-01-28", "commits": 1 },
    { "date": "2024-01-29", "commits": 10 },
    { "date": "2024-01-30", "commits": 5 },
    { "date": "2024-01-31", "commits": 11 },
    { "date": "2024-02-01", "commits": 12 },
    { "date": "2024-02-02", "commits": 15 },
    { "date": "2024-02-03", "commits": 1 },
    { "date": "2024-02-04", "commits": 2 },
    { "date": "2024-02-05", "commits": 10 },
    { "date": "2024-02-06", "commits": 9 },
    { "date": "2024-02-07", "commits": 12 },
    { "date": "2024-02-08", "commits": 6 },
    { "date": "2024-02-09", "commits": 13 },
    { "date": "2024-02-10", "commits": 1 },
    { "date": "2024-02-11", "commits": 1 },
    { "date": "2024-02-12", "commits": 7 },
    { "date": "2024-02-13", "commits": 17 },
    { "date": "2024-02-14", "commits": 16 },
    { "date": "2024-02-15", "commits": 17 },
    { "date": "2024-02-16", "commits": 10 },
    { "date": "2024-02-17", "commits": 1 },
    { "date": "2024-02-18", "commits": 1 },
    { "date": "2024-02-19", "commits": 11 },
    { "date": "2024-02-20", "commits": 6 },
    { "date": "2024-02-21", "commits": 15 },
    { "date": "2024-02-22", "commits": 17 },
    { "date": "2024-02-23", "commits": 5 },
    { "date": "2024-02-24", "commits": 1 },
    { "date": "2024-02-25", "commits": 2 },
    { "date": "2024-02-26", "commits": 14 },
    { "date": "2024-02-27", "commits": 12 },
    { "date": "2024-02-28", "commits": 18 },
    { "date": "2024-02-29", "commits": 9 },
    { "date": "2024-03-01", "commits": 16 },
    { "date": "2024-03-02", "commits": 1 },
    { "date": "2024-03-03", "commits": 1 },
    { "date": "2024-03-04", "commits": 15 },
    { "date": "2024-03-05", "commits": 5 },
    { "date": "2024-03-06", "commits": 9 },
    { "date": "2024-03-07", "commits": 12 },
    { "date": "2024-03-08", "commits": 16 },
    { "date": "2024-03-09", "commits": 2 },
    { "date": "2024-03-10", "commits": 1 },
    { "date": "2024-03-11", "commits": 11 },
    { "date": "2024-03-12", "commits": 14 },
    { "date": "2024-03-13", "commits": 18 },
    { "date": "2024-03-14", "commits": 14 },
    { "date": "2024-03-15", "commits": 9 },
    { "date": "2024-03-16", "commits": 1 },
    { "date": "2024-03-17", "commits": 2 },
    { "date": "2024-03-18", "commits": 9 },
    { "date": "2024-03-19", "commits": 18 },
    { "date": "2024-03-20", "commits": 16 },
    { "date": "2024-03-21", "commits": 8 },
    { "date": "2024-03-22", "commits": 18 },
    { "date": "2024-03-23", "commits": 1 },
    { "date": "2024-03-24", "commits": 3 },
    { "date": "2024-03-25", "commits": 30 },
    { "date": "2024-03-26", "commits": 19 },
    { "date": "2024-03-27", "commits": 12 },
    { "date": "2024-03-28", "commits": 11 },
    { "date": "2024-03-29", "commits": 9 },
    { "date": "2024-03-30", "commits": 1 },
    { "date": "2024-03-31", "commits": 2 },
    { "date": "2024-04-01", "commits": 7 },
    { "date": "2024-04-02", "commits": 18 },
    { "date": "2024-04-03", "commits": 19 },
    { "date": "2024-04-04", "commits": 15 },
    { "date": "2024-04-05", "commits": 10 },
    { "date": "2024-04-06", "commits": 1 },
    { "date": "2024-04-07", "commits": 1 },
    { "date": "2024-04-08", "commits": 18 },
    { "date": "2024-04-09", "commits": 9 },
    { "date": "2024-04-10", "commits": 14 },
    { "date": "2024-04-11", "commits": 16 },
    { "date": "2024-04-12", "commits": 14 },
    { "date": "2024-04-13", "commits": 2 },
    { "date": "2024-04-14", "commits": 2 },
    { "date": "2024-04-15", "commits": 15 },
    { "date": "2024-04-16", "commits": 7 },
    { "date": "2024-04-17", "commits": 15 },
    { "date": "2024-04-18", "commits": 17 },
    { "date": "2024-04-19", "commits": 8 },
    { "date": "2024-04-20", "commits": 1 },
    { "date": "2024-04-21", "commits": 2 },
    { "date": "2024-04-22", "commits": 11 },
    { "date": "2024-04-23", "commits": 19 },
    { "date": "2024-04-24", "commits": 18 },
    { "date": "2024-04-25", "commits": 6 },
    { "date": "2024-04-26", "commits": 16 },
    { "date": "2024-04-27", "commits": 1 },
    { "date": "2024-04-28", "commits": 2 },
    { "date": "2024-04-29", "commits": 13 },
    { "date": "2024-04-30", "commits": 6 },
    { "date": "2024-05-01", "commits": 16 },
    { "date": "2024-05-02", "commits": 7 },
    { "date": "2024-05-03", "commits": 19 },
    { "date": "2024-05-04", "commits": 1 },
    { "date": "2024-05-05", "commits": 1 },
    { "date": "2024-05-06", "commits": 12 },
    { "date": "2024-05-07", "commits": 17 },
    { "date": "2024-05-08", "commits": 11 },
    { "date": "2024-05-09", "commits": 10 },
    { "date": "2024-05-10", "commits": 19 },
    { "date": "2024-05-11", "commits": 2 },
    { "date": "2024-05-12", "commits": 1 },
    { "date": "2024-05-13", "commits": 7 },
    { "date": "2024-05-14", "commits": 17 },
    { "date": "2024-05-15", "commits": 7 },
    { "date": "2024-05-16", "commits": 18 },
    { "date": "2024-05-17", "commits": 10 },
    { "date": "2024-05-18", "commits": 1 },
    { "date": "2024-05-19", "commits": 1 },
    { "date": "2024-05-20", "commits": 8 },
    { "date": "2024-05-21", "commits": 18 },
    { "date": "2024-05-22", "commits": 12 },
    { "date": "2024-05-23", "commits": 19 },
    { "date": "2024-05-24", "commits": 17 },
    { "date": "2024-05-25", "commits": 2 },
    { "date": "2024-05-26", "commits": 2 },
    { "date": "2024-05-27", "commits": 11 },
    { "date": "2024-05-28", "commits": 13 },
    { "date": "2024-05-29", "commits": 14 },
    { "date": "2024-05-30", "commits": 14 },
    { "date": "2024-05-31", "commits": 12 },
    { "date": "2024-06-01", "commits": 1 },
    { "date": "2024-06-02", "commits": 1 },
    { "date": "2024-06-03", "commits": 15 },
    { "date": "2024-06-04", "commits": 15 },
    { "date": "2024-06-05", "commits": 17 },
    { "date": "2024-06-06", "commits": 8 },
    { "date": "2024-06-07", "commits": 17 },
    { "date": "2024-06-08", "commits": 2 },
    { "date": "2024-06-09", "commits": 1 },
    { "date": "2024-06-10", "commits": 9 },
    { "date": "2024-06-11", "commits": 11 },
    { "date": "2024-06-12", "commits": 16 },
    { "date": "2024-06-13", "commits": 12 },
    { "date": "2024-06-14", "commits": 11 },
    { "date": "2024-06-15", "commits": 1 },
    { "date": "2024-06-16", "commits": 2 },
    { "date": "2024-06-17", "commits": 13 },
    { "date": "2024-06-18", "commits": 16 },
    { "date": "2024-06-19", "commits": 12 },
    { "date": "2024-06-20", "commits": 18 },
    { "date": "2024-06-21", "commits": 9 },
    { "date": "2024-06-22", "commits": 1 },
    { "date": "2024-06-23", "commits": 2 },
    { "date": "2024-06-24", "commits": 12 },
    { "date": "2024-06-25", "commits": 12 },
    { "date": "2024-06-26", "commits": 14 },
    { "date": "2024-06-27", "commits": 14 },
    { "date": "2024-06-28", "commits": 24 },
    { "date": "2024-06-29", "commits": 2 },
    { "date": "2024-06-30", "commits": 2 },
    { "date": "2024-07-01", "commits": 17 },
    { "date": "2024-07-02", "commits": 9 },
    { "date": "2024-07-03", "commits": 18 },
    { "date": "2024-07-04", "commits": 16 },
    { "date": "2024-07-05", "commits": 7 },
    { "date": "2024-07-06", "commits": 1 },
    { "date": "2024-07-07", "commits": 1 },
    { "date": "2024-07-08", "commits": 21 },
    { "date": "2024-07-09", "commits": 15 },
    { "date": "2024-07-10", "commits": 7 },
    { "date": "2024-07-11", "commits": 9 },
    { "date": "2024-07-12", "commits": 21 },
    { "date": "2024-07-13", "commits": 1 },
    { "date": "2024-07-14", "commits": 2 },
    { "date": "2024-07-15", "commits": 20 },
    { "date": "2024-07-16", "commits": 20 },
    { "date": "2024-07-17", "commits": 16 },
    { "date": "2024-07-18", "commits": 22 },
    { "date": "2024-07-19", "commits": 18 },
    { "date": "2024-07-20", "commits": 2 },
    { "date": "2024-07-21", "commits": 2 },
    { "date": "2024-07-22", "commits": 7 },
    { "date": "2024-07-23", "commits": 20 },
    { "date": "2024-07-24", "commits": 22 },
    { "date": "2024-07-25", "commits": 14 },
    { "date": "2024-07-26", "commits": 18 },
    { "date": "2024-07-27", "commits": 1 },
    { "date": "2024-07-28", "commits": 2 },
    { "date": "2024-07-29", "commits": 9 },
    { "date": "2024-07-30", "commits": 17 },
    { "date": "2024-07-31", "commits": 18 },
    { "date": "2024-08-01", "commits": 17 },
    { "date": "2024-08-02", "commits": 19 },
    { "date": "2024-08-03", "commits": 1 },
    { "date": "2024-08-04", "commits": 1 },
    { "date": "2024-08-05", "commits": 2 },
    { "date": "2024-08-06", "commits": 1 },
    { "date": "2024-08-07", "commits": 1 },
    { "date": "2024-08-08", "commits": 2 },
    { "date": "2024-08-09", "commits": 2 },
    { "date": "2024-08-12", "commits": 2 },
    { "date": "2024-08-13", "commits": 1 },
    { "date": "2024-08-14", "commits": 3 },
    { "date": "2024-08-15", "commits": 2 },
    { "date": "2024-08-16", "commits": 2 },
    { "date": "2024-08-19", "commits": 18 },
    { "date": "2024-08-20", "commits": 15 },
    { "date": "2024-08-21", "commits": 19 },
    { "date": "2024-08-22", "commits": 18 },
    { "date": "2024-08-23", "commits": 7 },
    { "date": "2024-08-24", "commits": 2 },
    { "date": "2024-08-25", "commits": 1 },
    { "date": "2024-08-26", "commits": 12 },
    { "date": "2024-08-27", "commits": 14 },
    { "date": "2024-08-28", "commits": 12 },
    { "date": "2024-08-29", "commits": 11 },
    { "date": "2024-08-30", "commits": 11 },
    { "date": "2024-08-31", "commits": 1 },
    { "date": "2024-09-01", "commits": 1 },
    { "date": "2024-09-02", "commits": 20 },
    { "date": "2024-09-03", "commits": 22 },
    { "date": "2024-09-04", "commits": 11 },
    { "date": "2024-09-05", "commits": 19 },
    { "date": "2024-09-06", "commits": 15 },
    { "date": "2024-09-07", "commits": 2 },
    { "date": "2024-09-08", "commits": 1 },
    { "date": "2024-09-09", "commits": 8 },
    { "date": "2024-09-10", "commits": 22 },
    { "date": "2024-09-11", "commits": 23 },
    { "date": "2024-09-12", "commits": 9 },
    { "date": "2024-09-13", "commits": 19 },
    { "date": "2024-09-14", "commits": 1 },
    { "date": "2024-09-15", "commits": 2 },
    { "date": "2024-09-16", "commits": 11 },
    { "date": "2024-09-17", "commits": 13 },
    { "date": "2024-09-18", "commits": 11 },
    { "date": "2024-09-19", "commits": 12 },
    { "date": "2024-09-20", "commits": 18 },
    { "date": "2024-09-21", "commits": 2 },
    { "date": "2024-09-22", "commits": 1 },
    { "date": "2024-09-23", "commits": 15 },
    { "date": "2024-09-24", "commits": 37 },
    { "date": "2024-09-25", "commits": 38 },
    { "date": "2024-09-26", "commits": 30 },
    { "date": "2024-09-27", "commits": 39 },
    { "date": "2024-09-28", "commits": 2 },
    { "date": "2024-09-29", "commits": 2 },
    { "date": "2024-09-30", "commits": 30 },
    { "date": "2024-10-01", "commits": 22 },
    { "date": "2024-10-02", "commits": 19 },
    { "date": "2024-10-03", "commits": 24 },
    { "date": "2024-10-04", "commits": 19 },
    { "date": "2024-10-05", "commits": 1 },
    { "date": "2024-10-06", "commits": 1 },
    { "date": "2024-10-07", "commits": 23 },
    { "date": "2024-10-08", "commits": 9 },
    { "date": "2024-10-09", "commits": 21 },
    { "date": "2024-10-10", "commits": 14 },
    { "date": "2024-10-11", "commits": 12 },
    { "date": "2024-10-12", "commits": 1 },
    { "date": "2024-10-13", "commits": 1 },
    { "date": "2024-10-14", "commits": 8 },
    { "date": "2024-10-15", "commits": 8 },
    { "date": "2024-10-16", "commits": 21 },
    { "date": "2024-10-17", "commits": 13 },
    { "date": "2024-10-18", "commits": 23 },
    { "date": "2024-10-19", "commits": 1 },
    { "date": "2024-10-20", "commits": 1 },
    { "date": "2024-10-21", "commits": 15 },
    { "date": "2024-10-22", "commits": 17 },
    { "date": "2024-10-23", "commits": 19 },
    { "date": "2024-10-24", "commits": 24 },
    { "date": "2024-10-25", "commits": 19 },
    { "date": "2024-10-26", "commits": 1 },
    { "date": "2024-10-27", "commits": 2 },
    { "date": "2024-10-28", "commits": 16 },
    { "date": "2024-10-29", "commits": 22 },
    { "date": "2024-10-30", "commits": 13 },
    { "date": "2024-10-31", "commits": 23 },
    { "date": "2024-11-01", "commits": 16 },
    { "date": "2024-11-02", "commits": 1 },
    { "date": "2024-11-03", "commits": 2 },
    { "date": "2024-11-04", "commits": 20 },
    { "date": "2024-11-05", "commits": 17 },
    { "date": "2024-11-06", "commits": 13 },
    { "date": "2024-11-07", "commits": 14 },
    { "date": "2024-11-08", "commits": 19 },
    { "date": "2024-11-09", "commits": 1 },
    { "date": "2024-11-10", "commits": 1 },
    { "date": "2024-11-11", "commits": 25 },
    { "date": "2024-11-12", "commits": 8 },
    { "date": "2024-11-13", "commits": 24 },
    { "date": "2024-11-14", "commits": 10 },
    { "date": "2024-11-15", "commits": 15 },
    { "date": "2024-11-16", "commits": 2 },
    { "date": "2024-11-17", "commits": 2 },
    { "date": "2024-11-18", "commits": 11 },
    { "date": "2024-11-19", "commits": 7 },
    { "date": "2024-11-20", "commits": 15 },
    { "date": "2024-11-21", "commits": 22 },
    { "date": "2024-11-22", "commits": 8 },
    { "date": "2024-11-23", "commits": 1 },
    { "date": "2024-11-24", "commits": 2 },
    { "date": "2024-11-25", "commits": 19 },
    { "date": "2024-11-26", "commits": 8 },
    { "date": "2024-11-27", "commits": 17 },
    { "date": "2024-11-28", "commits": 9 },
    { "date": "2024-11-29", "commits": 25 },
    { "date": "2024-11-30", "commits": 1 },
    { "date": "2024-12-01", "commits": 1 },
    { "date": "2024-12-02", "commits": 13 },
    { "date": "2024-12-03", "commits": 12 },
    { "date": "2024-12-04", "commits": 10 },
    { "date": "2024-12-05", "commits": 14 },
    { "date": "2024-12-06", "commits": 8 },
    { "date": "2024-12-07", "commits": 1 },
    { "date": "2024-12-08", "commits": 1 },
    { "date": "2024-12-09", "commits": 16 },
    { "date": "2024-12-10", "commits": 8 },
    { "date": "2024-12-11", "commits": 19 },
    { "date": "2024-12-12", "commits": 23 },
    { "date": "2024-12-13", "commits": 22 },
    { "date": "2024-12-14", "commits": 2 },
    { "date": "2024-12-15", "commits": 2 },
    { "date": "2024-12-16", "commits": 9 },
    { "date": "2024-12-17", "commits": 24 },
    { "date": "2024-12-18", "commits": 21 },
    { "date": "2024-12-19", "commits": 18 },
    { "date": "2024-12-20", "commits": 21 },
    { "date": "2024-12-21", "commits": 1 },
    { "date": "2024-12-22", "commits": 1 },
    { "date": "2024-12-23", "commits": 24 },
    { "date": "2024-12-24", "commits": 37 },
    { "date": "2024-12-25", "commits": 17 },
    { "date": "2024-12-26", "commits": 34 },
    { "date": "2024-12-27", "commits": 24 },
    { "date": "2024-12-28", "commits": 2 },
    { "date": "2024-12-29", "commits": 3 },
    { "date": "2024-12-30", "commits": 24 },
    { "date": "2024-12-31", "commits": 33 }
  ],
  "date": "date",
  "value": "commits",
  "title": "Commits per day to the main repository, 2024",
  "subtitle": "Number of commits each day",
  "note": "Illustrative data. Pale cells are days with no commits."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `date` (required) | `string` |  | Date field: ISO strings, Dates or epoch milliseconds. One cell per calendar day. |
| `value` (required) | `string` |  | Numeric field that colours each day. Rows sharing a day are summed. |
| `orientation` | `"auto" \| "horizontal" \| "vertical"` | `"auto"` | Weeks left to right, or top to bottom. `auto` goes vertical under 480px. |
| `weekStart` | `"monday" \| "sunday"` | `"monday"` | First day of the week. |
| `domain` | `[number, number]` |  | Fix the ends of the colour scale. Default: 0 to the maximum. |
| `height` | `number \| string` |  | Common prop, but note the default: when omitted the height follows the cell size, which follows the width, so cells stay square. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Three years, with a gap in the record

```tsx
import { CalendarHeatmap } from "insightcharts";

const data = [
  { day: "2022-01-01", steps: 3996 },
  { day: "2022-01-02", steps: 1946 },
  { day: "2022-01-03", steps: 3651 },
  { day: "2022-01-04", steps: 4872 },
  { day: "2022-01-05", steps: 2206 },
  { day: "2022-01-06", steps: 1736 },
  { day: "2022-01-07", steps: 4042 },
  { day: "2022-01-08", steps: 5780 },
  // ... 1058 more rows
];

<CalendarHeatmap
  data={data}
  date="day"
  value="steps"
  format="compact"
  title="Steps per day, 2022 to 2024"
  subtitle="Daily step count. There is no data for April 2023."
  note="Illustrative data"
/>
```

#### Sparse events, Sunday start

```tsx
import { CalendarHeatmap } from "insightcharts";

const data = [
  { date: "2025-01-01", incidents: 3 },
  { date: "2025-01-06", incidents: 3 },
  { date: "2025-01-08", incidents: 2 },
  { date: "2025-01-11", incidents: 1 },
  { date: "2025-01-15", incidents: 2 },
  { date: "2025-01-16", incidents: 3 },
  { date: "2025-01-21", incidents: 2 },
  { date: "2025-01-22", incidents: 3 },
  // ... 106 more rows
];

<CalendarHeatmap
  data={data}
  date="date"
  value="incidents"
  weekStart="sunday"
  title="Incidents logged per day, 2025"
  subtitle="Daily incident count, weeks starting on Sunday"
  note="Illustrative data"
/>
```

#### Forced vertical with a fixed height

```tsx
import { CalendarHeatmap } from "insightcharts";

const data = [
  { date: "2024-01-01", commits: 16 },
  { date: "2024-01-02", commits: 9 },
  { date: "2024-01-03", commits: 8 },
  { date: "2024-01-04", commits: 6 },
  { date: "2024-01-05", commits: 8 },
  { date: "2024-01-06", commits: 1 },
  { date: "2024-01-07", commits: 1 },
  { date: "2024-01-08", commits: 17 },
  // ... 354 more rows
];

<CalendarHeatmap
  data={data}
  date="date"
  value="commits"
  orientation="vertical"
  height={520}
  style={{ maxWidth: 220 }}
  subtitle="Commits per day, 2024"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/calendar-heatmap.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/calendar-heatmap.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Callout (`callout`)

> A boxed statement of fact with a short bold lead and a sentence of explanation. The tone is marked by icon and tint.

- Component: `Callout` (import from `insightcharts`)
- Spec type: `"callout"`
- Level: atom. Category: text.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Beside or under a chart, to state its main fact in words, with the number. Also for a caveat the reader must not miss (`negative`).

### Avoid

Long narration (use `prose`), a featured number (use `big-number` or `stat-tile`), or more than one callout per chart.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/callout
```

The file lands at `components/insightcharts/atoms/callout.tsx`. `@insightcharts/callout-demo` adds a ready-made example next to it.

### Usage

```tsx
import { Callout } from "insightcharts";

<Callout
  tone="accent"
  label="Summary"
  lead="Solar supplied more than half of demand on 4 in 10 summer afternoons in 2024"
  text="Wholesale prices were below zero on those afternoons."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "callout",
  "tone": "accent",
  "label": "Summary",
  "lead": "Solar supplied more than half of demand on 4 in 10 summer afternoons in 2024",
  "text": "Wholesale prices were below zero on those afternoons."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `lead` | `string` |  | The fact in a few bold words. State it with its number. |
| `text` | `string` |  | One sentence of explanation or evidence. |
| `children` | `ReactNode` |  | JSX alternative to `text`. |
| `tone` | `"neutral" \| "positive" \| "negative" \| "accent"` | `"neutral"` | Sets the icon shape and the tint together. |
| `label` | `string` |  | Small label above the lead, e.g. "Summary". |
| `variant` | `"soft" \| "outline" \| "plain"` | `"soft"` | Tinted box, bordered box, or no box. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [chart-callout](https://insightcharts.dev/llms/chart-callout.md), [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md), [data-explorer](https://insightcharts.dev/llms/data-explorer.md), [explainer](https://insightcharts.dev/llms/explainer.md)

### More examples

#### Positive

```tsx
import { Callout } from "insightcharts";

<Callout
  tone="positive"
  lead="Monthly churn fell from 4.2% to 2.1% between January and June"
  text="It has stayed at 2.1% for two quarters since."
/>
```

#### Negative caveat, outline

```tsx
import { Callout } from "insightcharts";

<Callout
  tone="negative"
  variant="outline"
  label="Caveat"
  lead="2020 figures are not comparable"
  text="The survey moved online during lockdown. Response rates among over-75s fell by a third. Treat 2020 as a break in the series."
/>
```

#### Neutral, plain

```tsx
import { Callout } from "insightcharts";

<Callout
  tone="neutral"
  variant="plain"
  text="Figures are provisional until the statistical office publishes its annual revision in September."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/callout.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/callout.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Choropleth map (`choropleth-map`)

> Colours the regions of a map by a normalised value, from GeoJSON you supply.

- Component: `ChoroplethMap` (import from `insightcharts`)
- Spec type: `"choropleth-map"`
- Level: atom. Category: geo.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A rate, share or per-capita figure that varies by place, where the geographic pattern (a north-south divide, a cluster) is what the reader needs to see. Use a diverging scale for change or for values either side of a meaningful midpoint.

### Avoid

Raw counts, which mostly map population (normalise first, or use bar-chart); ranking regions precisely (use bar-chart); a handful of regions with no spatial pattern (use bar-chart); regions so different in size that small ones vanish (use a tile-grid GeoJSON).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/choropleth-map
```

The file lands at `components/insightcharts/atoms/choropleth-map.tsx`. `@insightcharts/choropleth-map-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ChoroplethMap } from "insightcharts";

const data = [
  { state: "Queensland", share: 45 },
  { state: "South Australia", share: 47 },
  { state: "Western Australia", share: 39 },
  { state: "New South Wales", share: 31 },
  { state: "Australian Capital Territory", share: 29 },
  { state: "Victoria", share: 26 },
  { state: "Northern Territory", share: 22 },
  { state: "Tasmania", share: 19 },
];

<ChoroplethMap
  geo={{
    type: "FeatureCollection",
    features: [
      {
        type: "Feature",
        properties: { name: "Western Australia", code: "WA" },
        geometry: { type: "Polygon", coordinates: [[[0, 1], [4, 1], [4, 6], [0, 6], [0, 1]]] },
      },
      {
        type: "Feature",
        properties: { name: "Northern Territory", code: "NT" },
        geometry: { type: "Polygon", coordinates: [[[4, 3.5], [6.5, 3.5], [6.5, 6.5], [4, 6.5], [4, 3.5]]] },
      },
      {
        type: "Feature",
        properties: { name: "South Australia", code: "SA" },
        geometry: { type: "Polygon", coordinates: [[[4, 1], [6.5, 1], [6.5, 3.5], [4, 3.5], [4, 1]]] },
      },
      {
        type: "Feature",
        properties: { name: "Queensland", code: "Qld" },
        geometry: {
          type: "Polygon",
          coordinates: [
            [
              [6.5, 3],
              [10, 3],
              [10, 5.2],
              [8.6, 5.2],
              [8.6, 7.2],
              [7.6, 7.2],
              [7.6, 6.2],
              [6.5, 6.2],
              [6.5, 3],
            ],
          ],
        },
      },
      {
        type: "Feature",
        properties: { name: "New South Wales", code: "NSW" },
        geometry: {
          type: "Polygon",
          coordinates: [
            [[6.5, 1.4], [10, 1.4], [10, 3], [6.5, 3], [6.5, 1.4]],
            [[8.7, 1.8], [8.7, 2.4], [9.4, 2.4], [9.4, 1.8], [8.7, 1.8]],
          ],
        },
      },
      {
        type: "Feature",
        properties: { name: "Australian Capital Territory", code: "ACT" },
        geometry: {
          type: "Polygon",
          coordinates: [[[8.7, 1.8], [9.4, 1.8], [9.4, 2.4], [8.7, 2.4], [8.7, 1.8]]],
        },
      },
      {
        type: "Feature",
        properties: { name: "Victoria", code: "Vic" },
        geometry: {
          type: "Polygon",
          coordinates: [[[6.5, 0.3], [9.2, 0.3], [9.2, 1.4], [6.5, 1.4], [6.5, 0.3]]],
        },
      },
      {
        type: "Feature",
        properties: { name: "Tasmania", code: "Tas" },
        geometry: {
          type: "Polygon",
          coordinates: [[[7.6, -1.1], [8.7, -1.1], [8.7, -0.3], [7.6, -0.3], [7.6, -1.1]]],
        },
      },
    ],
  }}
  data={data}
  region="state"
  value="share"
  format="{value}%"
  aspectScale={1}
  labels
  labelProperty="code"
  height={380}
  title="47% of homes in South Australia had rooftop solar in 2023"
  subtitle="Share of dwellings with a solar installation, by state and territory, 2023"
  source="Australian PV Institute"
  note="Approximate figures on a simplified block map"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "choropleth-map",
  "geo": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": { "name": "Western Australia", "code": "WA" },
        "geometry": { "type": "Polygon", "coordinates": [[[0, 1], [4, 1], [4, 6], [0, 6], [0, 1]]] }
      },
      {
        "type": "Feature",
        "properties": { "name": "Northern Territory", "code": "NT" },
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[4, 3.5], [6.5, 3.5], [6.5, 6.5], [4, 6.5], [4, 3.5]]]
        }
      },
      {
        "type": "Feature",
        "properties": { "name": "South Australia", "code": "SA" },
        "geometry": { "type": "Polygon", "coordinates": [[[4, 1], [6.5, 1], [6.5, 3.5], [4, 3.5], [4, 1]]] }
      },
      {
        "type": "Feature",
        "properties": { "name": "Queensland", "code": "Qld" },
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [6.5, 3],
              [10, 3],
              [10, 5.2],
              [8.6, 5.2],
              [8.6, 7.2],
              [7.6, 7.2],
              [7.6, 6.2],
              [6.5, 6.2],
              [6.5, 3]
            ]
          ]
        }
      },
      {
        "type": "Feature",
        "properties": { "name": "New South Wales", "code": "NSW" },
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [[6.5, 1.4], [10, 1.4], [10, 3], [6.5, 3], [6.5, 1.4]],
            [[8.7, 1.8], [8.7, 2.4], [9.4, 2.4], [9.4, 1.8], [8.7, 1.8]]
          ]
        }
      },
      {
        "type": "Feature",
        "properties": { "name": "Australian Capital Territory", "code": "ACT" },
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[8.7, 1.8], [9.4, 1.8], [9.4, 2.4], [8.7, 2.4], [8.7, 1.8]]]
        }
      },
      {
        "type": "Feature",
        "properties": { "name": "Victoria", "code": "Vic" },
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[6.5, 0.3], [9.2, 0.3], [9.2, 1.4], [6.5, 1.4], [6.5, 0.3]]]
        }
      },
      {
        "type": "Feature",
        "properties": { "name": "Tasmania", "code": "Tas" },
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[7.6, -1.1], [8.7, -1.1], [8.7, -0.3], [7.6, -0.3], [7.6, -1.1]]]
        }
      }
    ]
  },
  "data": [
    { "state": "Queensland", "share": 45 },
    { "state": "South Australia", "share": 47 },
    { "state": "Western Australia", "share": 39 },
    { "state": "New South Wales", "share": 31 },
    { "state": "Australian Capital Territory", "share": 29 },
    { "state": "Victoria", "share": 26 },
    { "state": "Northern Territory", "share": 22 },
    { "state": "Tasmania", "share": 19 }
  ],
  "region": "state",
  "value": "share",
  "format": "{value}%",
  "aspectScale": 1,
  "labels": true,
  "labelProperty": "code",
  "height": 380,
  "title": "47% of homes in South Australia had rooftop solar in 2023",
  "subtitle": "Share of dwellings with a solar installation, by state and territory, 2023",
  "source": "Australian PV Institute",
  "note": "Approximate figures on a simplified block map"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `geo` (required) | `GeoJSON FeatureCollection \| string` |  | The map: a GeoJSON object, or a URL to fetch one from. Registered with ECharts automatically. |
| `region` (required) | `string` |  | Row field holding the region name that joins to the GeoJSON. |
| `value` (required) | `string` |  | Row field holding the value. Use a rate or share, not a raw count. |
| `nameProperty` | `string` | `"name"` | GeoJSON feature property holding each region's name. |
| `scale` | `"sequential" \| "diverging"` | `"sequential"` | Sequential for magnitude; diverging for values either side of a midpoint. |
| `midpoint` | `number` | `0` | Centre of the diverging scale. |
| `domain` | `[number, number]` |  | Fix the colour scale instead of using the data's range. |
| `labels` | `boolean \| "value"` | `false` | Print region names on the map; `"value"` adds the value on a second line. |
| `labelProperty` | `string` |  | GeoJSON feature property to print instead of the full name, e.g. a postal or ISO code. |
| `missingLabel` | `string` | `"No data"` | Legend text for regions without a value. |
| `aspectScale` | `number` | `0.75` | Horizontal stretch for longitude; 1 for tile maps and projected coordinates. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md)

### More examples

#### Diverging, with missing regions

```tsx
import { ChoroplethMap } from "insightcharts";

const data = [
  { state: "Queensland", net: 3.1 },
  { state: "Western Australia", net: 1.9 },
  { state: "South Australia", net: -0.2 },
  { state: "New South Wales", net: -3.4 },
  { state: "Victoria", net: -0.9 },
  { state: "Tasmania", net: -1.6 },
];

<ChoroplethMap
  geo={{
    type: "FeatureCollection",
    features: [
      {
        type: "Feature",
        properties: { name: "Western Australia", code: "WA" },
        geometry: { type: "Polygon", coordinates: [[[0, 1], [4, 1], [4, 6], [0, 6], [0, 1]]] },
      },
      {
        type: "Feature",
        properties: { name: "Northern Territory", code: "NT" },
        geometry: { type: "Polygon", coordinates: [[[4, 3.5], [6.5, 3.5], [6.5, 6.5], [4, 6.5], [4, 3.5]]] },
      },
      {
        type: "Feature",
        properties: { name: "South Australia", code: "SA" },
        geometry: { type: "Polygon", coordinates: [[[4, 1], [6.5, 1], [6.5, 3.5], [4, 3.5], [4, 1]]] },
      },
      {
        type: "Feature",
        properties: { name: "Queensland", code: "Qld" },
        geometry: {
          type: "Polygon",
          coordinates: [
            [
              [6.5, 3],
              [10, 3],
              [10, 5.2],
              [8.6, 5.2],
              [8.6, 7.2],
              [7.6, 7.2],
              [7.6, 6.2],
              [6.5, 6.2],
              [6.5, 3],
            ],
          ],
        },
      },
      {
        type: "Feature",
        properties: { name: "New South Wales", code: "NSW" },
        geometry: {
          type: "Polygon",
          coordinates: [
            [[6.5, 1.4], [10, 1.4], [10, 3], [6.5, 3], [6.5, 1.4]],
            [[8.7, 1.8], [8.7, 2.4], [9.4, 2.4], [9.4, 1.8], [8.7, 1.8]],
          ],
        },
      },
      {
        type: "Feature",
        properties: { name: "Australian Capital Territory", code: "ACT" },
        geometry: {
          type: "Polygon",
          coordinates: [[[8.7, 1.8], [9.4, 1.8], [9.4, 2.4], [8.7, 2.4], [8.7, 1.8]]],
        },
      },
      {
        type: "Feature",
        properties: { name: "Victoria", code: "Vic" },
        geometry: {
          type: "Polygon",
          coordinates: [[[6.5, 0.3], [9.2, 0.3], [9.2, 1.4], [6.5, 1.4], [6.5, 0.3]]],
        },
      },
      {
        type: "Feature",
        properties: { name: "Tasmania", code: "Tas" },
        geometry: {
          type: "Polygon",
          coordinates: [[[7.6, -1.1], [8.7, -1.1], [8.7, -0.3], [7.6, -0.3], [7.6, -1.1]]],
        },
      },
    ],
  }}
  data={data}
  region="state"
  value="net"
  scale="diverging"
  format="signed"
  labels
  labelProperty="code"
  aspectScale={1}
  height={380}
  highlight="Queensland"
  title="Queensland gained 3.1 people per 1,000 residents from interstate migration"
  subtitle="Net interstate migration per 1,000 residents, year to June"
  source="Illustrative data"
/>
```

#### Tile grid with labels, loaded from a URL

```tsx
import { ChoroplethMap } from "insightcharts";

const data = [
  { region: "North East", pay: 31.2 },
  { region: "North West", pay: 33.1 },
  { region: "Yorkshire", pay: 32.4 },
  { region: "West Midlands", pay: 33 },
  { region: "East Midlands", pay: 32.1 },
  { region: "East", pay: 36.3 },
  { region: "South West", pay: 33.5 },
  { region: "South East", pay: 38.4 },
  // ... 1 more rows
];

<ChoroplethMap
  geo="data:application/json,%7B%22type%22%3A%22FeatureCollection%22%2C%22features%22%3A%5B%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22North%20East%22%2C%22code%22%3A%22NE%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B2.03%2C-0.97%5D%2C%5B2.9699999999999998%2C-0.97%5D%2C%5B2.9699999999999998%2C-0.03%5D%2C%5B2.03%2C-0.03%5D%2C%5B2.03%2C-0.97%5D%5D%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22North%20West%22%2C%22code%22%3A%22NW%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B1.03%2C-1.97%5D%2C%5B1.97%2C-1.97%5D%2C%5B1.97%2C-1.03%5D%2C%5B1.03%2C-1.03%5D%2C%5B1.03%2C-1.97%5D%5D%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22Yorkshire%22%2C%22code%22%3A%22Yorks%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B2.03%2C-1.97%5D%2C%5B2.9699999999999998%2C-1.97%5D%2C%5B2.9699999999999998%2C-1.03%5D%2C%5B2.03%2C-1.03%5D%2C%5B2.03%2C-1.97%5D%5D%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22West%20Midlands%22%2C%22code%22%3A%22W%20Mids%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B1.03%2C-2.9699999999999998%5D%2C%5B1.97%2C-2.9699999999999998%5D%2C%5B1.97%2C-2.03%5D%2C%5B1.03%2C-2.03%5D%2C%5B1.03%2C-2.9699999999999998%5D%5D%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22East%20Midlands%22%2C%22code%22%3A%22E%20Mids%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B2.03%2C-2.9699999999999998%5D%2C%5B2.9699999999999998%2C-2.9699999999999998%5D%2C%5B2.9699999999999998%2C-2.03%5D%2C%5B2.03%2C-2.03%5D%2C%5B2.03%2C-2.9699999999999998%5D%5D%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22East%22%2C%22code%22%3A%22East%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B3.03%2C-2.9699999999999998%5D%2C%5B3.9699999999999998%2C-2.9699999999999998%5D%2C%5B3.9699999999999998%2C-2.03%5D%2C%5B3.03%2C-2.03%5D%2C%5B3.03%2C-2.9699999999999998%5D%5D%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22South%20West%22%2C%22code%22%3A%22SW%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B1.03%2C-3.9699999999999998%5D%2C%5B1.97%2C-3.9699999999999998%5D%2C%5B1.97%2C-3.03%5D%2C%5B1.03%2C-3.03%5D%2C%5B1.03%2C-3.9699999999999998%5D%5D%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22South%20East%22%2C%22code%22%3A%22SE%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B2.03%2C-3.9699999999999998%5D%2C%5B2.9699999999999998%2C-3.9699999999999998%5D%2C%5B2.9699999999999998%2C-3.03%5D%2C%5B2.03%2C-3.03%5D%2C%5B2.03%2C-3.9699999999999998%5D%5D%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22name%22%3A%22London%22%2C%22code%22%3A%22Lon%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B3.03%2C-3.9699999999999998%5D%2C%5B3.9699999999999998%2C-3.9699999999999998%5D%2C%5B3.9699999999999998%2C-3.03%5D%2C%5B3.03%2C-3.03%5D%2C%5B3.03%2C-3.9699999999999998%5D%5D%5D%7D%7D%5D%7D"
  data={data}
  region="region"
  value="pay"
  labels="value"
  labelProperty="code"
  format="£{value}k"
  aspectScale={1}
  height={340}
  title="Median full-time pay in London was £46,200 in 2023"
  subtitle="Median full-time annual earnings by English region, £ thousand, 2023"
  source="ONS Annual Survey of Hours and Earnings"
  note="Rounded. Each region is drawn as one equal tile"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/choropleth-map.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/choropleth-map.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Circle pack (`circle-pack`)

> Shows parts as tightly packed circles sized by value, optionally clustered into groups, with the value and name printed inside each circle.

- Component: `CirclePack` (import from `insightcharts`)
- Spec type: `"circle-pack"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A poster view of 5 to about 60 parts of very different sizes where the reader should see the largest ones and their rough proportions at once: budgets by programme, emissions by source, users by product. One level of grouping is supported.

### Avoid

Values that need precise comparison (use bar-chart, where bars share a baseline); parts that must visibly add up to a whole (use treemap or waffle-chart); more than about 80 parts (use treemap); negative values (use diverging-bar-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/circle-pack
```

The file lands at `components/insightcharts/atoms/circle-pack.tsx`. `@insightcharts/circle-pack-demo` adds a ready-made example next to it.

### Usage

```tsx
import { CirclePack } from "insightcharts";

const data = [
  { crop: "Maize", group: "Cereals", mt: 1160 },
  { crop: "Wheat", group: "Cereals", mt: 780 },
  { crop: "Rice", group: "Cereals", mt: 790 },
  { crop: "Barley", group: "Cereals", mt: 150 },
  { crop: "Sorghum", group: "Cereals", mt: 60 },
  { crop: "Potatoes", group: "Roots", mt: 375 },
  { crop: "Cassava", group: "Roots", mt: 330 },
  { crop: "Sweet potatoes", group: "Roots", mt: 90 },
  { crop: "Yams", group: "Roots", mt: 85 },
  { crop: "Soybeans", group: "Oil crops", mt: 350 },
  { crop: "Oil palm fruit", group: "Oil crops", mt: 420 },
  { crop: "Rapeseed", group: "Oil crops", mt: 87 },
  { crop: "Sunflower seed", group: "Oil crops", mt: 54 },
];

<CirclePack
  data={data}
  name="crop"
  value="mt"
  group="group"
  format="{value} Mt"
  title="The world harvested 1,160 million tonnes of maize in 2022"
  subtitle="Harvest of 13 major crops by group, million tonnes, 2022"
  source="FAOSTAT"
  note="Rounded, approximate figures for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "circle-pack",
  "data": [
    { "crop": "Maize", "group": "Cereals", "mt": 1160 },
    { "crop": "Wheat", "group": "Cereals", "mt": 780 },
    { "crop": "Rice", "group": "Cereals", "mt": 790 },
    { "crop": "Barley", "group": "Cereals", "mt": 150 },
    { "crop": "Sorghum", "group": "Cereals", "mt": 60 },
    { "crop": "Potatoes", "group": "Roots", "mt": 375 },
    { "crop": "Cassava", "group": "Roots", "mt": 330 },
    { "crop": "Sweet potatoes", "group": "Roots", "mt": 90 },
    { "crop": "Yams", "group": "Roots", "mt": 85 },
    { "crop": "Soybeans", "group": "Oil crops", "mt": 350 },
    { "crop": "Oil palm fruit", "group": "Oil crops", "mt": 420 },
    { "crop": "Rapeseed", "group": "Oil crops", "mt": 87 },
    { "crop": "Sunflower seed", "group": "Oil crops", "mt": 54 }
  ],
  "name": "crop",
  "value": "mt",
  "group": "group",
  "format": "{value} Mt",
  "title": "The world harvested 1,160 million tonnes of maize in 2022",
  "subtitle": "Harvest of 13 major crops by group, million tonnes, 2022",
  "source": "FAOSTAT",
  "note": "Rounded, approximate figures for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Name field: one circle per row. |
| `value` (required) | `string` |  | Value field: circle area. Non-positive values are dropped. |
| `group` | `string` |  | Parent field. Circles sharing a group sit together and share a colour. |
| `ring` | `"none" \| "group" \| "all"` |  | Thin dotted enclosing ring: one per group with its name and total, or one around the whole pack. Default "group" when `group` is set, else "none". |
| `colorBy` | `"group" \| "value" \| "single"` |  | Colour by group, shade by value along the sequential ramp, or use the accent for every circle. Default "group" when `group` is set, else "single". |
| `icon` | `string \| Record<string, string>` |  | Icon drawn above the number in large circles: one for all, or a map from circle or group name to icon. Built-in name or `path://`. |
| `sizeLegend` | `boolean \| number[]` | `false` | Size key of nested reference circles. `true` picks round values; an array sets them. |
| `labels` | `boolean` | `true` | Print names and values inside circles, and beside the ones too small to hold them. |
| `names` | `Record<string, string>` |  | Display names for group keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md)

### More examples

#### Flat, with highlight, icons and a size key

```tsx
import { CirclePack } from "insightcharts";

const data = [
  { service: "Schools", m: 412 },
  { service: "Public transport", m: 268 },
  { service: "Police", m: 231 },
  { service: "Waste and recycling", m: 96 },
  { service: "Social housing", m: 187 },
  { service: "Parks", m: 44 },
  { service: "Libraries", m: 23 },
  { service: "Street lighting", m: 17 },
  // ... 10 more rows
];

<CirclePack
  data={data}
  name="service"
  value="m"
  format="${value}m"
  highlight="Schools"
  icon={{ Schools: "house", "Public transport": "car", Parks: "tree" }}
  sizeLegend
  select
  title="Schools take $412 million of the city's $1,627 million budget"
  subtitle="Annual spending by service, $ million. Click a circle to select it."
  note="Illustrative figures for an invented city"
/>
```

#### Shaded by value inside one ring

```tsx
import { CirclePack } from "insightcharts";

const data = [
  { service: "Schools", m: 412 },
  { service: "Public transport", m: 268 },
  { service: "Police", m: 231 },
  { service: "Waste and recycling", m: 96 },
  { service: "Social housing", m: 187 },
  { service: "Parks", m: 44 },
  { service: "Libraries", m: 23 },
  { service: "Street lighting", m: 17 },
  // ... 1 more rows
];

<CirclePack
  data={data}
  name="service"
  value="m"
  format="${value}m"
  colorBy="value"
  ring="all"
  title="Nine services cost $1,366 million a year"
  subtitle="Annual spending by service, $ million"
  note="Illustrative figures for an invented city"
/>
```

#### Stress: 27 circles in 5 groups, long names, values from 2 to 1,280

```tsx
import { CirclePack } from "insightcharts";

const data = [
  { category: "Messaging", app: "Chatter", users: 940 },
  { category: "Messaging", app: "Paperplane", users: 310 },
  { category: "Messaging", app: "Hello Neighbour Community Boards", users: 42 },
  { category: "Messaging", app: "Ping", users: 18 },
  { category: "Messaging", app: "Semaphore", users: 6 },
  { category: "Video", app: "Loop", users: 1280 },
  { category: "Video", app: "Screening Room", users: 260 },
  { category: "Video", app: "Clipboard", users: 95 },
  // ... 19 more rows
];

<CirclePack
  data={data}
  name="app"
  value="users"
  group="category"
  format="{value}k"
  sizeLegend
  height={620}
  title="Loop has 1,280 thousand monthly users"
  subtitle="Monthly active users of 27 apps by category, thousands"
  note="Illustrative figures for an invented app catalogue"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/circle-pack.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/circle-pack.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Curve rank (`curve-rank`)

> Places each entity on two parallel scales, one per measure, and joins its two positions with a smooth S-curve labelled with the name and both values.

- Component: `CurveRank` (import from `insightcharts`)
- Spec type: `"curve-rank"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Two different measures of the same 4 to about 15 entities, when the point is how standing on one relates to standing on the other: price against sales, staff against output, cost against usage. Each side has its own scale, stated in its heading.

### Avoid

The same measure at two moments (use slope-chart); ranks across many periods (use bump-chart); more than about 15 entities or a statistical relationship (use scatter-chart); exact comparison on one measure (use bar-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/curve-rank
```

The file lands at `components/insightcharts/atoms/curve-rank.tsx`. `@insightcharts/curve-rank-demo` adds a ready-made example next to it.

### Usage

```tsx
import { CurveRank } from "insightcharts";

const data = [
  { drink: "Filter coffee", price: 2.4, cups: 310 },
  { drink: "Espresso", price: 2.6, cups: 145 },
  { drink: "Flat white", price: 3.6, cups: 260 },
  { drink: "Iced latte", price: 4.2, cups: 180 },
  { drink: "Matcha latte", price: 4.8, cups: 75 },
  { drink: "Hot chocolate", price: 3.9, cups: 40 },
];

<CurveRank
  data={data}
  name="drink"
  left="price"
  right="cups"
  leftLabel="Price per cup"
  rightLabel="Cups sold a day"
  leftFormat={{ style: "currency", currency: "GBP" }}
  leftTop="low"
  title="Filter coffee sold 310 cups a day at £2.40 a cup"
  subtitle="Price per cup and cups sold per day for six drinks at one café, cheapest at the top"
  note="Illustrative figures."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "curve-rank",
  "data": [
    { "drink": "Filter coffee", "price": 2.4, "cups": 310 },
    { "drink": "Espresso", "price": 2.6, "cups": 145 },
    { "drink": "Flat white", "price": 3.6, "cups": 260 },
    { "drink": "Iced latte", "price": 4.2, "cups": 180 },
    { "drink": "Matcha latte", "price": 4.8, "cups": 75 },
    { "drink": "Hot chocolate", "price": 3.9, "cups": 40 }
  ],
  "name": "drink",
  "left": "price",
  "right": "cups",
  "leftLabel": "Price per cup",
  "rightLabel": "Cups sold a day",
  "leftFormat": { "style": "currency", "currency": "GBP" },
  "leftTop": "low",
  "title": "Filter coffee sold 310 cups a day at £2.40 a cup",
  "subtitle": "Price per cup and cups sold per day for six drinks at one café, cheapest at the top",
  "note": "Illustrative figures."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Entity field: one curve per row. |
| `left` (required) | `string` |  | Field for the left-hand measure. |
| `right` (required) | `string` |  | Field for the right-hand measure. |
| `leftLabel` | `string` |  | Heading over the left rule: the measure and its unit. Defaults to the field name. |
| `rightLabel` | `string` |  | Heading over the right rule. Defaults to the field name. |
| `leftScale` | `"linear" \| "log"` | `"linear"` | Scale of the left measure. A log scale is stated in the heading. |
| `rightScale` | `"linear" \| "log"` | `"linear"` | Scale of the right measure. |
| `leftTop` | `"high" \| "low"` | `"high"` | Which end of the left measure sits at the top. |
| `rightTop` | `"high" \| "low"` | `"high"` | Which end of the right measure sits at the top. |
| `leftFormat` | `FormatSpec` |  | How to print left values. Defaults to `format`. |
| `rightFormat` | `FormatSpec` |  | How to print right values. Defaults to `format`. |
| `order` | `string[]` |  | Entity names in the order that assigns colours. Pass the same list to glyph-table to match its row colours. |
| `colorBy` | `"series" \| "none"` |  | `series`: one colour per entity; past the size of the theme's palette the extra colours are derived from the theme's own (glyph-table derives the same ones). `none`: every curve in the accent. Default: series while the entities fit the palette (at most 8), none beyond. |
| `names` | `Record<string, string>` |  | Display names for entity keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [matrix-poster](https://insightcharts.dev/llms/matrix-poster.md)

### More examples

#### One highlighted, log scale on the right

```tsx
import { CurveRank } from "insightcharts";

const data = [
  { venue: "Corner bakery", staff: 4, visits: 380 },
  { venue: "Riverside café", staff: 7, visits: 910 },
  { venue: "Station kiosk", staff: 2, visits: 2400 },
  { venue: "Market hall", staff: 18, visits: 5200 },
  { venue: "Museum restaurant", staff: 22, visits: 640 },
  { venue: "Food truck", staff: 3, visits: 720 },
  { venue: "Hotel bar", staff: 9, visits: 210 },
];

<CurveRank
  data={data}
  name="venue"
  left="staff"
  right="visits"
  leftLabel="Staff"
  rightLabel="Customers a day"
  rightScale="log"
  highlight="Station kiosk"
  title="The station kiosk served 2,400 customers a day with 2 staff"
  subtitle="Staff and daily customers at seven food venues in one town"
  note="Illustrative figures."
/>
```

#### Ten entities, one colour each

```tsx
import { CurveRank } from "insightcharts";

const data = [
  { district: "Old Town", rent: 1480, commute: 12 },
  { district: "Harbour", rent: 1390, commute: 15 },
  { district: "Riverside", rent: 1310, commute: 18 },
  { district: "University", rent: 1180, commute: 14 },
  { district: "Market", rent: 1120, commute: 20 },
  { district: "Hillcrest", rent: 1040, commute: 26 },
  { district: "Northgate", rent: 960, commute: 31 },
  { district: "Eastfield", rent: 890, commute: 34 },
  // ... 2 more rows
];

<CurveRank
  data={data}
  name="district"
  left="rent"
  right="commute"
  leftLabel="Median rent a month"
  rightLabel="Commute to the centre, minutes"
  leftFormat={{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }}
  rightFormat="{value} min"
  rightTop="low"
  colorBy="series"
  title="Old Town had a 12-minute commute at a median rent of €1,480 a month"
  subtitle="Median monthly rent and commute time to the centre for ten districts of one city, shortest commute at the top"
  note="Illustrative figures for an invented city."
/>
```

#### Stress: 14 entities, close values, long names

```tsx
import { CurveRank } from "insightcharts";

const data = [
  { service: "Northern Line Extension to the Harbour", satisfaction: 41, cost: 12.4 },
  { service: "Ring Road Bus Rapid Transit", satisfaction: 39, cost: 11.9 },
  { service: "Airport Express", satisfaction: 38, cost: 31 },
  { service: "Old Town Tram", satisfaction: 37, cost: 9.8 },
  { service: "University Shuttle", satisfaction: 22, cost: 3.1 },
  { service: "Riverside Ferry", satisfaction: 21, cost: 6.4 },
  { service: "Hillcrest Funicular", satisfaction: 20, cost: 6.2 },
  { service: "Night Bus Network", satisfaction: 19, cost: 6 },
  // ... 6 more rows
];

<CurveRank
  data={data}
  name="service"
  left="satisfaction"
  right="cost"
  leftLabel="Riders satisfied, %"
  rightLabel="Cost per trip, €"
  leftFormat="{value}%"
  rightFormat={{ style: "currency", currency: "EUR" }}
  highlight={["Demand-Responsive Minibus", "East-West Metro"]}
  title="The minibus cost €14.80 a trip with 7% of riders satisfied"
  subtitle="Share of riders satisfied and operating cost per trip for 14 transport services in one city"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/curve-rank.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/curve-rank.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Data table (`data-table`)

> A restrained editorial table from rows and a column config: aligned tabular numbers, an optional in-cell bar, row highlight and click-to-sort headers.

- Component: `DataTable` (import from `insightcharts`)
- Spec type: `"data-table"`
- Level: atom. Category: figure.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

When readers need to look up exact values, or compare a handful of entities across several measures with different units. Sort it by the column the caption refers to and highlight the row it names.

### Avoid

Showing a trend or a single comparison (use `line-chart` or `bar-chart`); more than about 7 columns or 30 rows without `maxHeight`.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/data-table
```

The file lands at `components/insightcharts/atoms/data-table.tsx`. `@insightcharts/data-table-demo` adds a ready-made example next to it.

### Usage

```tsx
import { DataTable } from "insightcharts";

<DataTable
  caption="Wind and solar supplied 67% of Denmark's electricity in 2024"
  subtitle="Electricity generation by country, 2024"
  source="Ember (illustrative figures)"
  highlight="Denmark"
  sort={{ key: "share", direction: "desc" }}
  columns={[
    { key: "country", label: "Country" },
    { key: "share", label: "Wind and solar share", format: "percent", bar: true, width: "38%" },
    { key: "twh", label: "Generation, TWh", format: "decimal:1" },
    {
      key: "change",
      label: "Change vs 2023",
      format: { style: "percent", signDisplay: "exceptZero", maximumFractionDigits: 1 },
    },
  ]}
  rows={[
    { country: "Germany", share: 0.43, twh: 209.4, change: 0.031 },
    { country: "Spain", share: 0.42, twh: 112.8, change: 0.044 },
    { country: "Denmark", share: 0.67, twh: 23.1, change: 0.012 },
    { country: "Netherlands", share: 0.41, twh: 49.6, change: 0.058 },
    { country: "Portugal", share: 0.46, twh: 22.9, change: 0.027 },
    { country: "France", share: 0.14, twh: 73.5, change: 0.009 },
    { country: "Poland", share: 0.24, twh: 40.2, change: -0.004 },
  ]}
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "data-table",
  "caption": "Wind and solar supplied 67% of Denmark's electricity in 2024",
  "subtitle": "Electricity generation by country, 2024",
  "source": "Ember (illustrative figures)",
  "highlight": "Denmark",
  "sort": { "key": "share", "direction": "desc" },
  "columns": [
    { "key": "country", "label": "Country" },
    {
      "key": "share",
      "label": "Wind and solar share",
      "format": "percent",
      "bar": true,
      "width": "38%"
    },
    { "key": "twh", "label": "Generation, TWh", "format": "decimal:1" },
    {
      "key": "change",
      "label": "Change vs 2023",
      "format": { "style": "percent", "signDisplay": "exceptZero", "maximumFractionDigits": 1 }
    }
  ],
  "rows": [
    { "country": "Germany", "share": 0.43, "twh": 209.4, "change": 0.031 },
    { "country": "Spain", "share": 0.42, "twh": 112.8, "change": 0.044 },
    { "country": "Denmark", "share": 0.67, "twh": 23.1, "change": 0.012 },
    { "country": "Netherlands", "share": 0.41, "twh": 49.6, "change": 0.058 },
    { "country": "Portugal", "share": 0.46, "twh": 22.9, "change": 0.027 },
    { "country": "France", "share": 0.14, "twh": 73.5, "change": 0.009 },
    { "country": "Poland", "share": 0.24, "twh": 40.2, "change": -0.004 }
  ]
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `rows` (required) | `Row[]` |  | One object per row. |
| `columns` | `(string \| { key, label?, format?, align?, bar?, sortable?, width? })[]` |  | Columns in order. Defaults to every key of the first row. Numeric columns are right-aligned. |
| `caption` | `string` |  | The table's title, as a real `<caption>`. |
| `subtitle` | `string` |  | Units and period, under the caption. |
| `source` | `string` |  | Shown under the table as "Source: ...". |
| `highlight` | `string \| number \| (string \| number)[]` |  | Rows to emphasise, matched on the first column (or `highlightKey`). |
| `highlightKey` | `string` |  | Field `highlight` matches against. |
| `sort` | `{ key, direction?: "asc" \| "desc" }` |  | Initial sort. |
| `sortable` | `boolean` | `true` | Click or press Enter on a header to sort; a third press restores the original order. |
| `maxHeight` | `number \| string` |  | Height before the body scrolls under the sticky header. |
| `density` | `"comfortable" \| "compact"` | `"comfortable"` | Row padding. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [data-explorer](https://insightcharts.dev/llms/data-explorer.md)

### More examples

#### Scrolling, sticky header, compact

```tsx
import { DataTable } from "insightcharts";

<DataTable
  caption="Twelve cities with a low-traffic centre"
  subtitle="Population in millions, liveability score out of 100, share of trips by bike"
  density="compact"
  maxHeight={260}
  columns={[
    { key: "city", label: "City" },
    { key: "population", label: "Population, m", format: "decimal:2" },
    { key: "startYear", label: "Scheme began" },
    { key: "score", label: "Score", format: "decimal:1" },
    { key: "cycling", label: "Cycling share", format: "percent" },
  ]}
  rows={[
    { city: "Vienna", population: 1.98, startYear: 2015, score: 71.2, cycling: 0.31 },
    { city: "Copenhagen", population: 0.66, startYear: 2012, score: 78.5, cycling: 0.49 },
    { city: "Amsterdam", population: 0.93, startYear: 2014, score: 75.1, cycling: 0.38 },
    { city: "Zurich", population: 0.44, startYear: 2011, score: 80.3, cycling: 0.27 },
    { city: "Helsinki", population: 0.67, startYear: 2016, score: 69.8, cycling: 0.22 },
    { city: "Munich", population: 1.51, startYear: 2018, score: 66.4, cycling: 0.19 },
    { city: "Oslo", population: 0.72, startYear: 2010, score: 82.6, cycling: 0.41 },
    { city: "Stockholm", population: 0.98, startYear: 2013, score: 77, cycling: 0.35 },
    { city: "Lyon", population: 0.52, startYear: 2019, score: 61.3, cycling: null },
    { city: "Ghent", population: 0.27, startYear: 2017, score: 64.9, cycling: 0.3 },
    { city: "Bologna", population: 0.39, startYear: 2020, score: 58.7, cycling: 0.12 },
    { city: "Ljubljana", population: 0.3, startYear: 2009, score: 73.4, cycling: 0.16 },
  ]}
  source="Illustrative data for the gallery"
/>
```

#### Default columns, no sorting

```tsx
import { DataTable } from "insightcharts";

<DataTable
  sortable={false}
  rows={[
    { Plan: "Starter", Seats: 5, "Price per seat": "$8", "Annual discount": "None" },
    { Plan: "Team", Seats: 25, "Price per seat": "$12", "Annual discount": "10%" },
    { Plan: "Enterprise", Seats: 250, "Price per seat": "Custom", "Annual discount": "Negotiated" },
  ]}
/>
```

#### Two highlighted rows, negative values

```tsx
import { DataTable } from "insightcharts";

<DataTable
  caption="Revenue grew in 2 of 5 regions in the fourth quarter"
  highlight={["North", "Islands"]}
  columns={[
    { key: "region", label: "Region" },
    { key: "revenue", label: "Revenue", format: "currency:EUR" },
    {
      key: "growth",
      label: "Quarterly growth",
      format: { style: "percent", signDisplay: "exceptZero", maximumFractionDigits: 1 },
      bar: true,
      width: "40%",
    },
  ]}
  rows={[
    { region: "North", revenue: 4820000, growth: 0.064 },
    { region: "South", revenue: 3950000, growth: -0.021 },
    { region: "East", revenue: 2210000, growth: -0.048 },
    { region: "West", revenue: 5130000, growth: -0.007 },
    { region: "Islands", revenue: 640000, growth: 0.112 },
  ]}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/data-table.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/data-table.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Delta (`delta`)

> An inline change indicator: direction arrow, signed value and an optional baseline label.

- Component: `Delta` (import from `insightcharts`)
- Spec type: `"delta"`
- Level: atom. Category: figure.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Next to a figure, in a sentence, a table cell or a tile, to say how much it changed and against what. Set `upIsGood: false` for measures where a fall is the good news (churn, emissions, wait times).

### Avoid

Standing alone as the main figure (use `big-number` or `stat-tile`, which include a delta). Do not omit the baseline label unless the surrounding text names it.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/delta
```

The file lands at `components/insightcharts/atoms/delta.tsx`. `@insightcharts/delta-demo` adds a ready-made example next to it.

### Usage

```tsx
import { Delta } from "insightcharts";

<Delta value={0.124} label="vs last quarter" size="md" />
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{ "type": "delta", "value": 0.124, "label": "vs last quarter", "size": "md" }
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `number \| string` |  | The change. Numbers format as signed percentages by default (0.12 is +12%). |
| `label` | `string` |  | The baseline, e.g. "vs last quarter". |
| `upIsGood` | `boolean` | `true` | Whether an increase is good news; decides the colour only. |
| `direction` | `"up" \| "down" \| "flat"` |  | Override the direction inferred from the sign. |
| `format` | `FormatSpec` | `signed percent` | Number format, e.g. `"signed"` for absolute changes or `"{value} pts"`. |
| `size` | `"sm" \| "md" \| "lg"` |  | 12, 14 or 16px. Inherits the surrounding size when omitted. |
| `variant` | `"text" \| "pill"` | `"text"` | `pill` adds a tinted capsule behind the value. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [before-after](https://insightcharts.dev/llms/before-after.md), [comparison-table](https://insightcharts.dev/llms/comparison-table.md), [ranked-list](https://insightcharts.dev/llms/ranked-list.md)

### More examples

#### Down is good (churn)

```tsx
import { Delta } from "insightcharts";

<Delta value={-0.021} label="monthly churn vs January" upIsGood={false} size="md" />
```

#### Down is bad, pill

```tsx
import { Delta } from "insightcharts";

<Delta value={-1840} format="signed" label="net subscribers this month" variant="pill" size="md" />
```

#### No change

```tsx
import { Delta } from "insightcharts";

<Delta value={0} label="vs 2023" size="md" />
```

#### String value, large pill

```tsx
import { Delta } from "insightcharts";

<Delta value="3 places" direction="up" label="in the regional ranking" variant="pill" size="lg" />
```

### Links

- Registry item: https://insightcharts.dev/r/delta.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/delta.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Diverging bar chart (`diverging-bar-chart`)

> Draws bars either side of a centre line: positive against negative values, or stacked agree / disagree responses around a neutral midpoint.

- Component: `DivergingBarChart` (import from `insightcharts`)
- Spec type: `"diverging-bar-chart"`
- Level: atom. Category: comparison.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Values that can be above or below zero (net change, balance, deviation from average); survey scales where the split between the two sides matters; two opposed groups back to back.

### Avoid

Values that are all positive (use bar-chart); parts that do not have a natural two-sided order (use a stacked bar-chart); change between two dates (use arrow-chart or dumbbell-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/diverging-bar-chart
```

The file lands at `components/insightcharts/atoms/diverging-bar-chart.tsx`. `@insightcharts/diverging-bar-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { DivergingBarChart } from "insightcharts";

const data = [
  { city: "Austin", change: 21.3 },
  { city: "Phoenix", change: 11.2 },
  { city: "Seattle", change: 8.1 },
  { city: "Chicago", change: -2.9 },
  { city: "San Francisco", change: -7.4 },
  { city: "St. Louis", change: -11.6 },
];

<DivergingBarChart
  data={data}
  x="city"
  y="change"
  format="{value}%"
  height={260}
  title="Austin's population grew 21.3% between 2010 and 2020"
  subtitle="Population change, 2010 to 2020"
  note="Illustrative figures."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "diverging-bar-chart",
  "data": [
    { "city": "Austin", "change": 21.3 },
    { "city": "Phoenix", "change": 11.2 },
    { "city": "Seattle", "change": 8.1 },
    { "city": "Chicago", "change": -2.9 },
    { "city": "San Francisco", "change": -7.4 },
    { "city": "St. Louis", "change": -11.6 }
  ],
  "x": "city",
  "y": "change",
  "format": "{value}%",
  "height": 260,
  "title": "Austin's population grew 21.3% between 2010 and 2020",
  "subtitle": "Population change, 2010 to 2020",
  "note": "Illustrative figures."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Category field. |
| `y` (required) | `string \| string[]` |  | One signed value field, or several fields ordered from most negative to most positive. |
| `series` | `string` |  | Field that splits rows into ordered series (long data). |
| `neutral` | `string \| false` |  | Series centred on the midline. Default: the middle one of an odd number of series. |
| `percent` | `boolean` | `false` | Normalise each row to 100% (stacked series). |
| `colors` | `"polarity" \| "sentiment"` | `"polarity"` | Single series: diverging poles, or the positive / negative colours when one side is good and the other bad. |
| `sort` | `"none" \| "asc" \| "desc"` |  | Row order. Default: descending by value or by the positive side; data order for dates. |
| `orientation` | `"auto" \| "horizontal" \| "vertical"` | `"auto"` | Horizontal, except vertical for a single series over dates. |
| `labels` | `boolean` |  | Values at bar ends (single) or inside segments (stacked). Default: on when there is room. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Likert scale around a neutral midpoint

```tsx
import { DivergingBarChart } from "insightcharts";

const data = [
  { statement: "My manager gives me useful feedback", sd: 4, d: 9, n: 14, a: 45, sa: 28 },
  { statement: "I have the tools I need to do my job", sd: 6, d: 15, n: 17, a: 42, sa: 20 },
  { statement: "I see a path to advance here", sd: 14, d: 24, n: 22, a: 28, sa: 12 },
  { statement: "My workload is manageable", sd: 19, d: 30, n: 16, a: 27, sa: 8 },
  { statement: "Pay is fair for the work I do", sd: 23, d: 31, n: 18, a: 21, sa: 7 },
];

<DivergingBarChart
  data={data}
  x="statement"
  y={["sd", "d", "n", "a", "sa"]}
  names={{ sd: "Strongly disagree", d: "Disagree", n: "Neither", a: "Agree", sa: "Strongly agree" }}
  format="{value}%"
  height={300}
  title="73% of staff agree their manager gives useful feedback"
  subtitle="Share of employees responding to each statement"
  note="Illustrative figures."
/>
```

#### Two opposed groups, long format

```tsx
import { DivergingBarChart } from "insightcharts";

const data = [
  { age: "75+", sex: "Men", share: 3.1 },
  { age: "75+", sex: "Women", share: 4.6 },
  { age: "60 to 74", sex: "Men", share: 7.9 },
  { age: "60 to 74", sex: "Women", share: 8.6 },
  { age: "45 to 59", sex: "Men", share: 10.2 },
  { age: "45 to 59", sex: "Women", share: 10.4 },
  { age: "30 to 44", sex: "Men", share: 10.1 },
  { age: "30 to 44", sex: "Women", share: 9.9 },
  // ... 4 more rows
];

<DivergingBarChart
  data={data}
  x="age"
  y="share"
  series="sex"
  sort="none"
  format="{value}%"
  height={280}
  title="Women aged 75 and over make up 4.6% of the population"
  subtitle="Share of total population by age group and sex"
  note="Illustrative figures."
/>
```

#### Vertical over time, good and bad

```tsx
import { DivergingBarChart } from "insightcharts";

const data = [
  { month: "2024-01", jobs: 119 },
  { month: "2024-02", jobs: 222 },
  { month: "2024-03", jobs: 246 },
  { month: "2024-04", jobs: 118 },
  { month: "2024-05", jobs: 193 },
  { month: "2024-06", jobs: 87 },
  { month: "2024-07", jobs: -32 },
  { month: "2024-08", jobs: -71 },
  // ... 4 more rows
];

<DivergingBarChart
  data={data}
  x="month"
  y="jobs"
  colors="sentiment"
  height={280}
  title="Payroll employment fell by 71,000 in August 2024"
  subtitle="Monthly change in payroll employment, thousands"
  note="Illustrative figures."
/>
```

#### Stress: 14 long statements, one highlighted, normalised

```tsx
import { DivergingBarChart } from "insightcharts";

const data = [
  {
    statement: "The government should raise taxes on the highest earners",
    oppose: 420,
    unsure: 90,
    support: 180,
  },
  {
    statement: "Public transport should be free for people under 25",
    oppose: 367,
    unsure: 107,
    support: 251,
  },
  {
    statement: "The retirement age should rise in line with life expectancy",
    oppose: 314,
    unsure: 124,
    support: 322,
  },
  {
    statement: "New housing should be allowed on protected countryside",
    oppose: 261,
    unsure: 141,
    support: 393,
  },
  {
    statement: "Private cars should be banned from the city centre",
    oppose: 208,
    unsure: 158,
    support: 464,
  },
  {
    statement: "University tuition should be paid entirely by the state",
    oppose: 155,
    unsure: 95,
    support: 205,
  },
  {
    statement: "The country should build new nuclear power stations",
    oppose: 402,
    unsure: 112,
    support: 276,
  },
  {
    statement: "Immigration quotas should be set by regional governments",
    oppose: 349,
    unsure: 129,
    support: 347,
  },
  // ... 6 more rows
];

<DivergingBarChart
  data={data}
  x="statement"
  y={["oppose", "unsure", "support"]}
  names={{ oppose: "Oppose", unsure: "Not sure", support: "Support" }}
  percent
  highlight="Rents should be capped by law"
  title="42% of respondents support capping rents by law"
  subtitle="Share of respondents, normalised to 100% per statement"
  note="Synthetic data for layout testing."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/diverging-bar-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/diverging-bar-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Donut chart (`donut-chart`)

> Shows how 2 to 5 parts make up one whole, with each slice labelled by name and share.

- Component: `DonutChart` (import from `insightcharts`)
- Spec type: `"donut-chart"`
- Level: atom. Category: part-to-whole.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A simple composition with one dominant part, or one part the title is about, where the total itself is worth printing in the centre.

### Avoid

More than 5 categories or parts of similar size that must be ranked (use bar-chart); a single figure (use big-number); composition compared across groups or time (use bar-chart with stack "percent"); a compact card (use segmented-bar).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/donut-chart
```

The file lands at `components/insightcharts/atoms/donut-chart.tsx`. `@insightcharts/donut-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { DonutChart } from "insightcharts";

const data = [
  { tenure: "Own outright", households: 8.8 },
  { tenure: "Own with a mortgage", households: 7.4 },
  { tenure: "Rent privately", households: 4.9 },
  { tenure: "Rent social housing", households: 4.1 },
];

<DonutChart
  data={data}
  name="tenure"
  value="households"
  format="{value}m"
  centerLabel="households"
  highlight="Rent privately"
  title="4.9 million households in England rented privately in 2022-23"
  subtitle="Households by tenure, England, 2022-23"
  source="English Housing Survey"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "donut-chart",
  "data": [
    { "tenure": "Own outright", "households": 8.8 },
    { "tenure": "Own with a mortgage", "households": 7.4 },
    { "tenure": "Rent privately", "households": 4.9 },
    { "tenure": "Rent social housing", "households": 4.1 }
  ],
  "name": "tenure",
  "value": "households",
  "format": "{value}m",
  "centerLabel": "households",
  "highlight": "Rent privately",
  "title": "4.9 million households in England rented privately in 2022-23",
  "subtitle": "Households by tenure, England, 2022-23",
  "source": "English Housing Survey",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Category field: one slice per distinct value. |
| `value` (required) | `string` |  | Value field. |
| `maxSlices` | `number` | `5` | Most slices drawn, including "Other"; smaller categories are folded. |
| `centerLabel` | `string` |  | Small label in the hole, e.g. "Total". Turns the centre text on. |
| `centerValue` | `string \| number` |  | Big text in the hole. Default: the formatted total when `centerLabel` is set. |
| `otherLabel` | `string` | `"Other"` | Name of the folded slice. |
| `names` | `Record<string, string>` |  | Display names for category keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [poster](https://insightcharts.dev/llms/poster.md)

### More examples

#### Two slices, no centre

```tsx
import { DonutChart } from "insightcharts";

const data = [{ answer: "Remote or hybrid", share: 41 }, { answer: "On site every day", share: 59 }];

<DonutChart
  data={data}
  name="answer"
  value="share"
  format="{value}%"
  highlight="Remote or hybrid"
  title="41% of employed adults work remotely or hybrid"
  subtitle="Share of employed adults by working pattern"
  source="Illustrative survey data"
/>
```

#### Folded into Other, custom centre

```tsx
import { DonutChart } from "insightcharts";

const data = [
  { source: "Coal", twh: 10434 },
  { source: "Gas", twh: 6634 },
  { source: "Hydro", twh: 4210 },
  { source: "Nuclear", twh: 2686 },
  { source: "Wind", twh: 2304 },
  { source: "Solar", twh: 1631 },
  { source: "Bioenergy", twh: 697 },
  { source: "Other fossil", twh: 786 },
  // ... 1 more rows
];

<DonutChart
  data={data}
  name="source"
  value="twh"
  format="compact"
  centerLabel="TWh generated"
  centerValue="29,471"
  title="Coal generated 35% of the world's electricity in 2023"
  subtitle="Global electricity generation by source, 2023, terawatt-hours"
  source="Ember, Global Electricity Review 2024"
  note="Figures are approximate, for illustration"
/>
```

#### Stress: long names and a sliver

```tsx
import { DonutChart } from "insightcharts";

const data = [
  { item: "Salaries, pensions and other staff-related expenditure", cost: 612 },
  { item: "Buildings and facilities management", cost: 188 },
  { item: "Information technology and software licences", cost: 94 },
  { item: "Travel", cost: 3 },
];

<DonutChart
  data={data}
  name="item"
  value="cost"
  format="currency:GBP"
  centerLabel="Total budget"
  title="Staff costs made up 68% of the departmental budget"
  subtitle="Departmental spending by category, £ thousands"
  source="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/donut-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/donut-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Dumbbell chart (`dumbbell-chart`)

> Shows two values per category as dots joined by a line, so the length of the line shows the difference.

- Component: `DumbbellChart` (import from `insightcharts`)
- Spec type: `"dumbbell-chart"`
- Level: atom. Category: comparison.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Before / after or group A / group B across up to about 20 categories, when the size of the difference is what the reader needs.

### Avoid

A single value per category (use lollipop-chart or bar-chart); when the direction of change matters more than the two levels (use arrow-chart); more than two points in time (use slope-chart or line-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/dumbbell-chart
```

The file lands at `components/insightcharts/atoms/dumbbell-chart.tsx`. `@insightcharts/dumbbell-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { DumbbellChart } from "insightcharts";

const data = [
  { country: "South Korea", y2000: 76, y2023: 83.6 },
  { country: "Turkey", y2000: 71.1, y2023: 77.3 },
  { country: "Poland", y2000: 73.8, y2023: 78.6 },
  { country: "Japan", y2000: 81.2, y2023: 84.1 },
  { country: "Germany", y2000: 78.2, y2023: 81.2 },
  { country: "United States", y2000: 76.7, y2023: 78.4 },
];

<DumbbellChart
  data={data}
  category="country"
  from="y2000"
  to="y2023"
  names={{ y2000: "2000", y2023: "2023" }}
  gapLabel="Gain"
  format="decimal:1"
  height={280}
  title="Life expectancy in South Korea rose from 76.0 years in 2000 to 83.6 in 2023"
  subtitle="Life expectancy at birth, years, 2000 and 2023"
  source="OECD Health Statistics (rounded)"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "dumbbell-chart",
  "data": [
    { "country": "South Korea", "y2000": 76, "y2023": 83.6 },
    { "country": "Turkey", "y2000": 71.1, "y2023": 77.3 },
    { "country": "Poland", "y2000": 73.8, "y2023": 78.6 },
    { "country": "Japan", "y2000": 81.2, "y2023": 84.1 },
    { "country": "Germany", "y2000": 78.2, "y2023": 81.2 },
    { "country": "United States", "y2000": 76.7, "y2023": 78.4 }
  ],
  "category": "country",
  "from": "y2000",
  "to": "y2023",
  "names": { "y2000": "2000", "y2023": "2023" },
  "gapLabel": "Gain",
  "format": "decimal:1",
  "height": 280,
  "title": "Life expectancy in South Korea rose from 76.0 years in 2000 to 83.6 in 2023",
  "subtitle": "Life expectancy at birth, years, 2000 and 2023",
  "source": "OECD Health Statistics (rounded)",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `category` (required) | `string` |  | Category field: one row of the chart each. |
| `from` (required) | `string` |  | Field with the first value, or (long data) the `series` value that marks it. |
| `to` (required) | `string` |  | Field with the second value, or (long data) the `series` value that marks it. |
| `series` | `string` |  | Long data: the field whose values are `from` and `to`. |
| `value` | `string` | `"value"` | Long data: the measure field. |
| `kind` | `"change" \| "groups"` | `"change"` | `change` draws a tint then the accent (before / after); `groups` uses two hues (two peers). |
| `sort` | `"gap" \| "from" \| "to" \| "none"` | `"gap"` | Row order. |
| `order` | `"desc" \| "asc"` | `"desc"` | Sort direction. |
| `labels` | `boolean` |  | Value labels beside both dots. Default: on for up to 14 rows; otherwise a value axis is drawn. |
| `gapLabel` | `boolean \| string` | `false` | Print the gap in a right-hand column; a string sets the column header. |
| `zero` | `boolean` | `false` | Start the value axis at zero. |
| `names` | `Record<string, string>` |  | Display names for the `from` and `to` keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [executive-brief](https://insightcharts.dev/llms/executive-brief.md)

### More examples

#### Two groups, highlighted row

```tsx
import { DumbbellChart } from "insightcharts";

const data = [
  { country: "South Korea", men: 100, women: 68.8 },
  { country: "Japan", men: 100, women: 78.7 },
  { country: "United States", men: 100, women: 83 },
  { country: "United Kingdom", men: 100, women: 85.5 },
  { country: "Germany", men: 100, women: 85.6 },
  { country: "France", men: 100, women: 88.4 },
  { country: "Sweden", men: 100, women: 92.7 },
  { country: "Belgium", men: 100, women: 98.8 },
];

<DumbbellChart
  data={data}
  category="country"
  from="women"
  to="men"
  kind="groups"
  names={{ men: "Men", women: "Women" }}
  highlight="South Korea"
  gapLabel="Gap"
  title="Women in South Korea earned 68.8% of men's median pay in 2022"
  subtitle="Median full-time earnings, men = 100"
  source="OECD gender wage gap, 2022 (rounded)"
  note="Figures are approximate, for illustration"
/>
```

#### Long format

```tsx
import { DumbbellChart } from "insightcharts";

const data = [
  { city: "Lisbon", period: "2015", value: 860 },
  { city: "Lisbon", period: "2024", value: 1720 },
  { city: "Dublin", period: "2015", value: 1390 },
  { city: "Dublin", period: "2024", value: 2380 },
  { city: "Berlin", period: "2015", value: 780 },
  { city: "Berlin", period: "2024", value: 1310 },
  { city: "Madrid", period: "2015", value: 790 },
  { city: "Madrid", period: "2024", value: 1260 },
  // ... 2 more rows
];

<DumbbellChart
  data={data}
  category="city"
  series="period"
  value="value"
  from="2015"
  to="2024"
  format="currency:EUR"
  height={260}
  title="Rent in Lisbon rose from €860 in 2015 to €1,720 in 2024"
  subtitle="Typical monthly rent for a one-bedroom flat, euros"
  note="Illustrative figures."
/>
```

#### Stress: 22 rows, long names, axis instead of labels

```tsx
import { DumbbellChart } from "insightcharts";

const data = [
  { sector: "Professional, scientific and technical services", before: 41, after: 63 },
  { sector: "Information and communication", before: 48, after: 66 },
  { sector: "Financial and insurance activities", before: 39, after: 58 },
  { sector: "Public administration and defence", before: 22, after: 44 },
  { sector: "Education", before: 18, after: 33 },
  { sector: "Real estate activities", before: 21, after: 35 },
  { sector: "Administrative and support services", before: 14, after: 26 },
  { sector: "Arts, entertainment and recreation", before: 11, after: 21 },
  // ... 14 more rows
];

<DumbbellChart
  data={data}
  category="sector"
  from="before"
  to="after"
  names={{ before: "2019", after: "2024" }}
  format="{value}%"
  title="Remote working in information and communication rose from 48% in 2019 to 66% in 2024"
  subtitle="Share of employees working from home at least one day a week, by sector"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/dumbbell-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/dumbbell-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Fan flow (`fan-flow`)

> One solid block that splits into curved ribbons, each as thick as its value, ending at an aligned column of names, values and shares.

- Component: `FanFlow` (import from `insightcharts`)
- Spec type: `"fan-flow"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

One total divided among 4 to about 14 destinations (or collected from that many origins, with `direction: "in"`) when the picture of the split is the point: where a budget goes, what a day's water is used for, which sources feed one total.

### Avoid

Flows with more than one stage or several sources (use sankey-chart); precise comparison of the parts (use bar-chart); 2 to 4 parts (use segmented-bar or donut-chart); values that can be negative (use bar-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/fan-flow
```

The file lands at `components/insightcharts/atoms/fan-flow.tsx`. `@insightcharts/fan-flow-demo` adds a ready-made example next to it.

### Usage

```tsx
import { FanFlow } from "insightcharts";

const data = [
  { use: "Shower", litres: 128 },
  { use: "Toilet", litres: 97 },
  { use: "Washing machine", litres: 62 },
  { use: "Kitchen tap", litres: 45 },
  { use: "Dishwasher", litres: 24 },
  { use: "Garden", litres: 21 },
  { use: "Bathroom tap", litres: 19 },
  { use: "Leaks", litres: 16 },
];

<FanFlow
  data={data}
  name="use"
  value="litres"
  trunk="Litres a day"
  tagged={["Shower", "Washing machine", "Dishwasher"]}
  tagLabel="Uses heated water"
  title="Showers used 128 of a household's 412 litres of water a day"
  subtitle="Daily water use of one four-person household by use, litres"
  note="Illustrative figures."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "fan-flow",
  "data": [
    { "use": "Shower", "litres": 128 },
    { "use": "Toilet", "litres": 97 },
    { "use": "Washing machine", "litres": 62 },
    { "use": "Kitchen tap", "litres": 45 },
    { "use": "Dishwasher", "litres": 24 },
    { "use": "Garden", "litres": 21 },
    { "use": "Bathroom tap", "litres": 19 },
    { "use": "Leaks", "litres": 16 }
  ],
  "name": "use",
  "value": "litres",
  "trunk": "Litres a day",
  "tagged": ["Shower", "Washing machine", "Dishwasher"],
  "tagLabel": "Uses heated water",
  "title": "Showers used 128 of a household's 412 litres of water a day",
  "subtitle": "Daily water use of one four-person household by use, litres",
  "note": "Illustrative figures."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Destination field: one ribbon per distinct value. |
| `value` (required) | `string` |  | Value field: ribbon thickness. Rows sharing a name are summed; non-positive values are dropped. |
| `trunk` | `string` |  | Label printed in the single block, with the total. |
| `direction` | `"out" \| "in"` | `"out"` | `out`: one block fans out to many labels on the right. `in`: many labels on the left flow into one block. |
| `maxItems` | `number` | `12` | Ribbons to keep; the rest are summed into the remainder ribbon. |
| `otherLabel` | `string` | `"Other"` | Name of the remainder ribbon, drawn in the context colour. A row with this name is treated as the remainder. |
| `tagged` | `string[]` |  | Destinations marked with a dotted outline around the name. |
| `tagLabel` | `string` |  | What the dotted outline means, printed in the key. Needed for `tagged` to be drawn. |
| `share` | `boolean` | `true` | Print each ribbon's share of the total. Dropped on narrow screens. |
| `colorBy` | `"series" \| "none"` |  | `series`: one colour per destination; past the size of the theme's palette the extra colours are derived from the theme's own. `none`: every ribbon in the accent. Default: series while the destinations fit the palette (at most 8), none beyond. |
| `sort` | `"value" \| "none"` | `"value"` | Largest first, or the data order. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [flow-poster](https://insightcharts.dev/llms/flow-poster.md)

### More examples

#### Many into one, with highlight

```tsx
import { FanFlow } from "insightcharts";

const data = [
  { district: "Riverside", riders: 2600 },
  { district: "Old Town", riders: 2150 },
  { district: "Hillcrest", riders: 1700 },
  { district: "Northgate", riders: 1250 },
  { district: "Mill Quarter", riders: 900 },
  { district: "Eastfield", riders: 520 },
  { district: "Lakeside", riders: 280 },
];

<FanFlow
  data={data}
  name="district"
  value="riders"
  direction="in"
  trunk="Riders arriving at Central Station"
  highlight="Riverside"
  format="integer"
  title="Riverside sent 2,600 of the 9,400 daily riders arriving at Central Station"
  subtitle="Riders arriving at Central Station on a weekday by home district"
  note="Illustrative figures for an invented city."
/>
```

#### One colour

```tsx
import { FanFlow } from "insightcharts";

const data = [
  { item: "Rent", amount: 1180 },
  { item: "Food", amount: 520 },
  { item: "Transport", amount: 240 },
  { item: "Energy", amount: 190 },
  { item: "Savings", amount: 150 },
  { item: "Other", amount: 120 },
];

<FanFlow
  data={data}
  name="item"
  value="amount"
  colorBy="none"
  trunk="Monthly take-home pay"
  format="€{value}"
  title="Rent took €1,180 of a €2,400 monthly pay packet"
  subtitle="Monthly spending of one renter by category, euros"
  note="Illustrative figures."
/>
```

#### Ten destinations, one colour each

```tsx
import { FanFlow } from "insightcharts";

const data = [
  { service: "Schools", spend: 212 },
  { service: "Social care", spend: 164 },
  { service: "Transport", spend: 121 },
  { service: "Housing", spend: 96 },
  { service: "Waste", spend: 71 },
  { service: "Police", spend: 64 },
  { service: "Parks", spend: 42 },
  { service: "Fire service", spend: 38 },
  // ... 2 more rows
];

<FanFlow
  data={data}
  name="service"
  value="spend"
  colorBy="series"
  trunk="City budget"
  format="€{value}m"
  title="Schools took €212m of one city's €850m budget"
  subtitle="Annual spending of one city council by service, millions of euros"
  note="Illustrative figures for an invented city."
/>
```

#### Stress: 18 destinations, long names, very uneven values

```tsx
import { FanFlow } from "insightcharts";

const data = [
  { line: "Salaries and employer contributions for teaching staff", pounds: 48200000 },
  { line: "Building maintenance, heating and electricity", pounds: 9100000 },
  { line: "Special educational needs support", pounds: 7400000 },
  { line: "Catering", pounds: 3900000 },
  { line: "Administration and office staff", pounds: 3600000 },
  { line: "Books, software licences and classroom equipment", pounds: 2100000 },
  { line: "School trips", pounds: 640000 },
  { line: "Sports hall hire", pounds: 410000 },
  // ... 10 more rows
];

<FanFlow
  data={data}
  name="line"
  value="pounds"
  maxItems={10}
  otherLabel="8 smaller lines"
  trunk="Annual budget"
  tagged={["Catering", "School trips", "Music lessons"]}
  tagLabel="Partly paid by parents"
  format="currency:GBP"
  title="Teaching salaries took £48.2m of one school's £76.9m budget"
  subtitle="Annual spending of one secondary school by budget line, pounds"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/fan-flow.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/fan-flow.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Funnel chart (`funnel-chart`)

> Shows how many remain at each step of a sequence, with conversion and drop-off between steps.

- Component: `FunnelChart` (import from `insightcharts`)
- Spec type: `"funnel-chart"`
- Level: atom. Category: flow.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A strict sequence where each stage is a subset of the one before: sign-up flows, hiring pipelines, sales stages, applications to admissions. 3 to 7 stages.

### Avoid

Stages that are not sequential subsets, or categories with no order (use bar-chart); flows that split to several destinations (use sankey-chart); conversion tracked over time (use line-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/funnel-chart
```

The file lands at `components/insightcharts/atoms/funnel-chart.tsx`. `@insightcharts/funnel-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { FunnelChart } from "insightcharts";

const data = [
  { step: "Visited the pricing page", users: 48200 },
  { step: "Started a free trial", users: 9640 },
  { step: "Connected a data source", users: 5310 },
  { step: "Invited a teammate", users: 2230 },
  { step: "Became a paying customer", users: 1480 },
];

<FunnelChart
  data={data}
  stage="step"
  value="users"
  format="integer"
  title="20% of pricing-page visitors started a free trial"
  subtitle="Users reaching each step of the sign-up funnel, last 90 days"
  source="Product analytics"
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "funnel-chart",
  "data": [
    { "step": "Visited the pricing page", "users": 48200 },
    { "step": "Started a free trial", "users": 9640 },
    { "step": "Connected a data source", "users": 5310 },
    { "step": "Invited a teammate", "users": 2230 },
    { "step": "Became a paying customer", "users": 1480 }
  ],
  "stage": "step",
  "value": "users",
  "format": "integer",
  "title": "20% of pricing-page visitors started a free trial",
  "subtitle": "Users reaching each step of the sign-up funnel, last 90 days",
  "source": "Product analytics",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `stage` (required) | `string` |  | Stage field. Rows are read in data order; the first row is the top of the funnel. |
| `value` (required) | `string` |  | Count field. |
| `dropoff` | `boolean` | `true` | State the drop-off between consecutive stages. |
| `dropoffLabel` | `string` | `"dropped off"` | Word for what is lost between stages. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Three stages, highlight

```tsx
import { FunnelChart } from "insightcharts";

const data = [
  { stage: "Applied", people: 12400 },
  { stage: "Interviewed", people: 1860 },
  { stage: "Offered a place", people: 930 },
];

<FunnelChart
  data={data}
  stage="stage"
  value="people"
  highlight="Offered a place"
  dropoffLabel="rejected"
  height={220}
  title="930 of 12,400 applicants were offered a place"
  subtitle="Applications to the graduate scheme, 2024 intake"
  source="HR recruitment data"
  note="Illustrative data"
/>
```

#### Stress: seven stages, long names, big numbers

```tsx
import { FunnelChart } from "insightcharts";

const data = [
  { stage: "Impressions served across all paid channels", n: 18400000 },
  { stage: "Clicked through to the landing page", n: 2210000 },
  { stage: "Viewed at least one product", n: 1480000 },
  { stage: "Added an item to the basket", n: 412000 },
  { stage: "Reached checkout", n: 236000 },
  { stage: "Entered payment details", n: 171000 },
  { stage: "Completed purchase", n: 148000 },
];

<FunnelChart
  data={data}
  stage="stage"
  value="n"
  format="compact"
  height={420}
  title="12% of ad impressions led to a click"
  subtitle="Campaign funnel from ad impression to purchase, fourth quarter"
  source="Marketing analytics"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/funnel-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/funnel-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Glyph table (`glyph-table`)

> A table with one row per entity in which every number is drawn as a small form chosen per column (counted dots, squares or icons, a ring, a sized circle, a bar) with the value printed beside it.

- Component: `GlyphTable` (import from `insightcharts`)
- Spec type: `"glyph-table"`
- Level: atom. Category: poster.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Comparing 3 to about 12 entities across 2 to 5 measures with different units, when the table should read as a graphic: profiles of products, cities, teams or species. Pair it with curve-rank by passing both the same `order`.

### Avoid

Looking up many exact values, sorting, or more than about 12 rows (use data-table); one measure across entities (use bar-chart or pictogram-chart); a trend over time (use line-chart or small-multiples).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/glyph-table
```

The file lands at `components/insightcharts/atoms/glyph-table.tsx`. `@insightcharts/glyph-table-demo` adds a ready-made example next to it.

### Usage

```tsx
import { GlyphTable } from "insightcharts";

<GlyphTable
  caption="Filter coffee sold 310 cups a day at £2.40 a cup"
  subtitle="Six drinks at one café: price, cups sold per day, share ordered with oat milk, seconds to prepare and caffeine"
  note="Illustrative figures."
  name="drink"
  nameLabel="Drink"
  columns={[
    {
      field: "price",
      label: "Price per cup",
      glyph: "bar",
      format: { style: "currency", currency: "GBP" },
      max: 5,
    },
    { field: "cups", label: "Cups sold a day", glyph: "dots", unit: 10 },
    { field: "oat", label: "With oat milk", glyph: "ring", format: "{value}%" },
    { field: "seconds", label: "Seconds to prepare", glyph: "blocks", unit: 10 },
    { field: "caffeine", label: "Caffeine, mg", glyph: "circle" },
  ]}
  rows={[
    { drink: "Filter coffee", price: 2.4, cups: 310, oat: 8, seconds: 15, caffeine: 140 },
    { drink: "Espresso", price: 2.6, cups: 145, oat: null, seconds: 30, caffeine: 65 },
    { drink: "Flat white", price: 3.6, cups: 260, oat: 34, seconds: 95, caffeine: 130 },
    { drink: "Iced latte", price: 4.2, cups: 180, oat: 41, seconds: 70, caffeine: 130 },
    { drink: "Matcha latte", price: 4.8, cups: 75, oat: 57, seconds: 110, caffeine: 70 },
    { drink: "Hot chocolate", price: 3.9, cups: 40, oat: 22, seconds: 85, caffeine: 10 },
  ]}
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "glyph-table",
  "caption": "Filter coffee sold 310 cups a day at £2.40 a cup",
  "subtitle": "Six drinks at one café: price, cups sold per day, share ordered with oat milk, seconds to prepare and caffeine",
  "note": "Illustrative figures.",
  "name": "drink",
  "nameLabel": "Drink",
  "columns": [
    {
      "field": "price",
      "label": "Price per cup",
      "glyph": "bar",
      "format": { "style": "currency", "currency": "GBP" },
      "max": 5
    },
    { "field": "cups", "label": "Cups sold a day", "glyph": "dots", "unit": 10 },
    { "field": "oat", "label": "With oat milk", "glyph": "ring", "format": "{value}%" },
    { "field": "seconds", "label": "Seconds to prepare", "glyph": "blocks", "unit": 10 },
    { "field": "caffeine", "label": "Caffeine, mg", "glyph": "circle" }
  ],
  "rows": [
    {
      "drink": "Filter coffee",
      "price": 2.4,
      "cups": 310,
      "oat": 8,
      "seconds": 15,
      "caffeine": 140
    },
    { "drink": "Espresso", "price": 2.6, "cups": 145, "oat": null, "seconds": 30, "caffeine": 65 },
    { "drink": "Flat white", "price": 3.6, "cups": 260, "oat": 34, "seconds": 95, "caffeine": 130 },
    { "drink": "Iced latte", "price": 4.2, "cups": 180, "oat": 41, "seconds": 70, "caffeine": 130 },
    { "drink": "Matcha latte", "price": 4.8, "cups": 75, "oat": 57, "seconds": 110, "caffeine": 70 },
    { "drink": "Hot chocolate", "price": 3.9, "cups": 40, "oat": 22, "seconds": 85, "caffeine": 10 }
  ]
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `rows` (required) | `Row[]` |  | One object per entity. |
| `name` | `string` |  | Field holding the entity name. Defaults to the first key of the first row. |
| `nameLabel` | `string` |  | Heading of the name column. |
| `columns` (required) | `{ field, label?, glyph?: "dots" \| "blocks" \| "ring" \| "circle" \| "bar" \| "icons" \| "text", unit?, format?, max?, icon? }[]` |  | Glyph columns in order. `dots`, `blocks` and `icons` draw one mark per `unit` (default 1, raised to a round number when the largest value would not fit, and stated in the heading). `ring` fills to `max` (default 100, or 1 for fractions). `circle` is sized by area and `bar` by length against `max` (default: the column's largest value). `text` prints the value alone. |
| `order` | `string[]` |  | Entity names in display order; also assigns colours. Pass the same list to curve-rank to match its curve colours. |
| `highlight` | `string \| string[]` |  | Entities drawn in colour; every other row turns grey. |
| `colorBy` | `"series" \| "none"` |  | `series`: one colour per entity; past the size of the theme's palette the extra colours are derived from the theme's own (curve-rank derives the same ones). `none`: every row in the accent. Default: series while the rows fit the palette (at most 8), none beyond. |
| `caption` | `string` |  | The table's title, as a real `<caption>`. |
| `subtitle` | `string` |  | Measures, units and period, under the caption. |
| `source` | `string` |  | Shown under the table as "Source: ...". |
| `note` | `string` |  | Method notes or caveats, shown under the table. |
| `select` | `boolean` |  | Let readers click a row (or press Enter on it) to select it; the other rows fade. |
| `onSelect` | `(values: string[]) => void` |  | Called with the selected entity names whenever the selection changes. |
| `selected` | `string[]` |  | Controlled selection: the entity names currently selected. When given, the table shows exactly this list and a click only calls `onSelect`. Omit it and the table keeps its own selection. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [matrix-poster](https://insightcharts.dev/llms/matrix-poster.md), [profile-poster](https://insightcharts.dev/llms/profile-poster.md)

### More examples

#### Highlighted row, icons, selectable

```tsx
import { GlyphTable } from "insightcharts";

<GlyphTable
  caption="The night shift had 4 nurses for 28 beds"
  subtitle="Three shifts on one hospital ward: nurses on duty, occupied beds, share of call bells answered within 2 minutes"
  note="Illustrative figures."
  name="shift"
  nameLabel="Shift"
  highlight="Night"
  select
  columns={[
    { field: "nurses", label: "Nurses on duty", glyph: "icons", icon: "person" },
    { field: "beds", label: "Occupied beds", glyph: "blocks" },
    {
      field: "answered",
      label: "Bells answered in 2 minutes",
      glyph: "ring",
      format: "percent",
      max: 1,
    },
    { field: "handover", label: "Handover, minutes", glyph: "text" },
  ]}
  rows={[
    { shift: "Morning", nurses: 9, beds: 30, answered: 0.91, handover: 25 },
    { shift: "Evening", nurses: 7, beds: 29, answered: 0.84, handover: 20 },
    { shift: "Night", nurses: 4, beds: 28, answered: 0.62, handover: 15 },
  ]}
/>
```

#### Ten entities, one colour each

```tsx
import { GlyphTable } from "insightcharts";

<GlyphTable
  caption="Ten districts by rent, commute, green space and population"
  subtitle="Median monthly rent, minutes to the centre, share of land that is park and residents, ten districts of one city"
  note="Illustrative figures for an invented city."
  name="district"
  nameLabel="District"
  colorBy="series"
  columns={[
    {
      field: "rent",
      label: "Median rent a month",
      glyph: "bar",
      format: { style: "currency", currency: "EUR", maximumFractionDigits: 0 },
    },
    { field: "commute", label: "Minutes to the centre", glyph: "dots" },
    { field: "park", label: "Park land", glyph: "ring", format: "{value}%" },
    { field: "residents", label: "Residents", glyph: "circle", format: "integer" },
  ]}
  rows={[
    { district: "Old Town", rent: 1480, commute: 12, park: 9, residents: 18400 },
    { district: "Harbour", rent: 1390, commute: 15, park: 6, residents: 12100 },
    { district: "Riverside", rent: 1310, commute: 18, park: 22, residents: 21700 },
    { district: "University", rent: 1180, commute: 14, park: 15, residents: 26300 },
    { district: "Market", rent: 1120, commute: 20, park: 4, residents: 9800 },
    { district: "Hillcrest", rent: 1040, commute: 26, park: 31, residents: 15200 },
    { district: "Northgate", rent: 960, commute: 31, park: 12, residents: 30500 },
    { district: "Eastfield", rent: 890, commute: 34, park: 17, residents: 24900 },
    { district: "Mill Quarter", rent: 820, commute: 29, park: 8, residents: 7600 },
    { district: "Lakeside", rent: 760, commute: 41, park: 38, residents: 11300 },
  ]}
/>
```

#### Stress: 10 rows, long names, very uneven values, missing data

```tsx
import { GlyphTable } from "insightcharts";

<GlyphTable
  caption="Ten library branches by loans, visits and opening hours"
  subtitle="Loans per year, visits per day, hours open per week and share of loans that were e-books, 2024"
  note="Illustrative figures."
  name="branch"
  nameLabel="Branch"
  order={["Central Library and City Archive", "Riverside"]}
  columns={[
    { field: "loans", label: "Loans a year", glyph: "dots", format: "compact" },
    { field: "visits", label: "Visits a day", glyph: "circle", format: "integer" },
    { field: "hours", label: "Hours open a week", glyph: "bar", max: 84 },
    { field: "ebooks", label: "E-book share", glyph: "ring", format: "{value}%" },
  ]}
  rows={[
    { branch: "Riverside", loans: 88000, visits: 640, hours: 54, ebooks: 31 },
    {
      branch: "Central Library and City Archive",
      loans: 412000,
      visits: 3900,
      hours: 84,
      ebooks: 38,
    },
    { branch: "Hillcrest", loans: 61000, visits: 410, hours: 48, ebooks: 22 },
    {
      branch: "Northgate Community Hub and Learning Centre",
      loans: 47500,
      visits: 380,
      hours: 60,
      ebooks: 27,
    },
    { branch: "Old Town", loans: 39000, visits: 290, hours: 40, ebooks: 18 },
    { branch: "Mill Quarter", loans: 22000, visits: 150, hours: 32, ebooks: null },
    { branch: "Eastfield", loans: 18400, visits: 120, hours: 30, ebooks: 12 },
    { branch: "Lakeside", loans: 9600, visits: 70, hours: 24, ebooks: 9 },
    { branch: "Harbour reading room", loans: 2100, visits: 25, hours: 12, ebooks: null },
    { branch: "Mobile library van", loans: 900, visits: 40, hours: 18, ebooks: 3 },
  ]}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/glyph-table.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/glyph-table.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Headline (`headline`)

> The opening block of a piece or section: kicker, title, one-sentence deck and a byline/date line.

- Component: `Headline` (import from `insightcharts`)
- Spec type: `"headline"`
- Level: atom. Category: text.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

At the top of a data story (`page`), at the start of each chapter (`section`), or as the heading of a tile (`card`). Write the title as one plain fact with its number. Write the deck as a second plain sentence.

### Avoid

Titling a single chart: charts carry their own `title` and `subtitle`. For numbered chapters use `step-marker`.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/headline
```

The file lands at `components/insightcharts/atoms/headline.tsx`. `@insightcharts/headline-demo` adds a ready-made example next to it.

### Usage

```tsx
import { Headline } from "insightcharts";

<Headline
  size="page"
  kicker="Energy transition"
  title="Solar generated more electricity than coal in Europe in 2024"
  deck="Solar was the continent's second-largest source of electricity that year."
  byline="By Ana Ruiz and Tom Okafor"
  date="2025-03-14"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "headline",
  "size": "page",
  "kicker": "Energy transition",
  "title": "Solar generated more electricity than coal in Europe in 2024",
  "deck": "Solar was the continent's second-largest source of electricity that year.",
  "byline": "By Ana Ruiz and Tom Okafor",
  "date": "2025-03-14"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | One fact with its number, as a plain sentence. Wraps balanced. |
| `kicker` | `string` |  | Small label above the title: section, series or topic. Sentence case. |
| `deck` | `string` |  | One-sentence standfirst. |
| `byline` | `string` |  | Author line, shown as written, e.g. "By Ana Ruiz". |
| `date` | `string` |  | ISO dates are formatted for the locale and wrapped in `<time>`; other strings are shown as written. |
| `size` | `"page" \| "section" \| "card"` | `"section"` | Type scale. Titles step down automatically in narrow containers. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | Heading level. Defaults to 1 (page), 2 (section), 3 (card). |
| `align` | `"left" \| "center"` | `"left"` | Text alignment. |
| `children` | `ReactNode` |  | Extra content under the byline. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [hero-figure](https://insightcharts.dev/llms/hero-figure.md), [section](https://insightcharts.dev/llms/section.md), [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md), [data-explorer](https://insightcharts.dev/llms/data-explorer.md), [executive-brief](https://insightcharts.dev/llms/executive-brief.md), [explainer](https://insightcharts.dev/llms/explainer.md), [report-page](https://insightcharts.dev/llms/report-page.md), [scorecard](https://insightcharts.dev/llms/scorecard.md), [timeline-story](https://insightcharts.dev/llms/timeline-story.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Section

```tsx
import { Headline } from "insightcharts";

<Headline
  size="section"
  kicker="Chapter 2"
  title="Germany and the Netherlands have more solar installations per person than Spain"
  deck="Solar installations per person, by country."
/>
```

#### Card

```tsx
import { Headline } from "insightcharts";

<Headline
  size="card"
  title="Wholesale electricity prices by hour, summer 2024"
  deck="Median day-ahead price for each hour of the day."
  date="Updated June 2024"
/>
```

#### Centered page, long title

```tsx
import { Headline } from "insightcharts";

<Headline
  size="page"
  align="center"
  title="Household energy bills in January 2025 were one third higher than before the price shock three years earlier"
  deck="Bills have fallen more slowly than forecast."
  byline="By the data desk"
  date="2025-01-09"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/headline.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/headline.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Heatmap (`heatmap`)

> Colours a category-by-category (or time-by-category) grid by a numeric value, using a sequential or diverging scale.

- Component: `Heatmap` (import from `insightcharts`)
- Spec type: `"heatmap"`
- Level: atom. Category: comparison.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Finding patterns across two dimensions at once: hour by weekday, cohort by month, product by region. Good when there are too many series for lines or bars and the overall pattern matters more than exact values.

### Avoid

Precise comparison of a few values (use bar-chart); a single series over time (use line-chart); a daily value across a year (use calendar-heatmap).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/heatmap
```

The file lands at `components/insightcharts/atoms/heatmap.tsx`. `@insightcharts/heatmap-demo` adds a ready-made example next to it.

### Usage

```tsx
import { Heatmap } from "insightcharts";

const data = [
  { day: "Mon", slot: "6am", orders: 12 },
  { day: "Mon", slot: "9am", orders: 48 },
  { day: "Mon", slot: "12pm", orders: 61 },
  { day: "Mon", slot: "3pm", orders: 55 },
  { day: "Mon", slot: "6pm", orders: 38 },
  { day: "Mon", slot: "9pm", orders: 14 },
  { day: "Tue", slot: "6am", orders: 11 },
  { day: "Tue", slot: "9am", orders: 52 },
  { day: "Tue", slot: "12pm", orders: 66 },
  { day: "Tue", slot: "3pm", orders: 58 },
  { day: "Tue", slot: "6pm", orders: 41 },
  { day: "Tue", slot: "9pm", orders: 15 },
  { day: "Wed", slot: "6am", orders: 13 },
  { day: "Wed", slot: "9am", orders: 55 },
  { day: "Wed", slot: "12pm", orders: 70 },
  { day: "Wed", slot: "3pm", orders: 63 },
  { day: "Wed", slot: "6pm", orders: 44 },
  { day: "Wed", slot: "9pm", orders: 17 },
  { day: "Thu", slot: "6am", orders: 12 },
  { day: "Thu", slot: "9am", orders: 51 },
  { day: "Thu", slot: "12pm", orders: 68 },
  { day: "Thu", slot: "3pm", orders: 60 },
  { day: "Thu", slot: "6pm", orders: 47 },
  { day: "Thu", slot: "9pm", orders: 22 },
  { day: "Fri", slot: "6am", orders: 10 },
  { day: "Fri", slot: "9am", orders: 44 },
  { day: "Fri", slot: "12pm", orders: 59 },
  { day: "Fri", slot: "3pm", orders: 49 },
  { day: "Fri", slot: "6pm", orders: 52 },
  { day: "Fri", slot: "9pm", orders: 35 },
  { day: "Sat", slot: "6am", orders: 6 },
  { day: "Sat", slot: "9am", orders: 18 },
  { day: "Sat", slot: "12pm", orders: 31 },
  { day: "Sat", slot: "3pm", orders: 36 },
  { day: "Sat", slot: "6pm", orders: 40 },
  { day: "Sat", slot: "9pm", orders: 38 },
  { day: "Sun", slot: "6am", orders: 5 },
  { day: "Sun", slot: "9am", orders: 14 },
  { day: "Sun", slot: "12pm", orders: 26 },
  { day: "Sun", slot: "3pm", orders: 30 },
  { day: "Sun", slot: "6pm", orders: 28 },
  { day: "Sun", slot: "9pm", orders: 19 },
];

<Heatmap
  data={data}
  x="slot"
  y="day"
  value="orders"
  title="Orders peak at 70 per hour at 12pm on Wednesdays"
  subtitle="Average orders per hour by weekday and time of day"
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "heatmap",
  "data": [
    { "day": "Mon", "slot": "6am", "orders": 12 },
    { "day": "Mon", "slot": "9am", "orders": 48 },
    { "day": "Mon", "slot": "12pm", "orders": 61 },
    { "day": "Mon", "slot": "3pm", "orders": 55 },
    { "day": "Mon", "slot": "6pm", "orders": 38 },
    { "day": "Mon", "slot": "9pm", "orders": 14 },
    { "day": "Tue", "slot": "6am", "orders": 11 },
    { "day": "Tue", "slot": "9am", "orders": 52 },
    { "day": "Tue", "slot": "12pm", "orders": 66 },
    { "day": "Tue", "slot": "3pm", "orders": 58 },
    { "day": "Tue", "slot": "6pm", "orders": 41 },
    { "day": "Tue", "slot": "9pm", "orders": 15 },
    { "day": "Wed", "slot": "6am", "orders": 13 },
    { "day": "Wed", "slot": "9am", "orders": 55 },
    { "day": "Wed", "slot": "12pm", "orders": 70 },
    { "day": "Wed", "slot": "3pm", "orders": 63 },
    { "day": "Wed", "slot": "6pm", "orders": 44 },
    { "day": "Wed", "slot": "9pm", "orders": 17 },
    { "day": "Thu", "slot": "6am", "orders": 12 },
    { "day": "Thu", "slot": "9am", "orders": 51 },
    { "day": "Thu", "slot": "12pm", "orders": 68 },
    { "day": "Thu", "slot": "3pm", "orders": 60 },
    { "day": "Thu", "slot": "6pm", "orders": 47 },
    { "day": "Thu", "slot": "9pm", "orders": 22 },
    { "day": "Fri", "slot": "6am", "orders": 10 },
    { "day": "Fri", "slot": "9am", "orders": 44 },
    { "day": "Fri", "slot": "12pm", "orders": 59 },
    { "day": "Fri", "slot": "3pm", "orders": 49 },
    { "day": "Fri", "slot": "6pm", "orders": 52 },
    { "day": "Fri", "slot": "9pm", "orders": 35 },
    { "day": "Sat", "slot": "6am", "orders": 6 },
    { "day": "Sat", "slot": "9am", "orders": 18 },
    { "day": "Sat", "slot": "12pm", "orders": 31 },
    { "day": "Sat", "slot": "3pm", "orders": 36 },
    { "day": "Sat", "slot": "6pm", "orders": 40 },
    { "day": "Sat", "slot": "9pm", "orders": 38 },
    { "day": "Sun", "slot": "6am", "orders": 5 },
    { "day": "Sun", "slot": "9am", "orders": 14 },
    { "day": "Sun", "slot": "12pm", "orders": 26 },
    { "day": "Sun", "slot": "3pm", "orders": 30 },
    { "day": "Sun", "slot": "6pm", "orders": 28 },
    { "day": "Sun", "slot": "9pm", "orders": 19 }
  ],
  "x": "slot",
  "y": "day",
  "value": "orders",
  "title": "Orders peak at 70 per hour at 12pm on Wednesdays",
  "subtitle": "Average orders per hour by weekday and time of day",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Column field: a category or a date. |
| `y` (required) | `string` |  | Row field. |
| `value` (required) | `string` |  | Numeric field that colours each cell. One data row per cell. |
| `diverging` | `boolean` | `false` | Diverging palette centred on `midpoint`, for values with a meaningful middle. |
| `midpoint` | `number` | `0` | Centre of the diverging scale. |
| `labels` | `boolean` |  | Print the value in each cell. Default: on when cells are large enough. |
| `sort` | `"none" \| "asc" \| "desc"` | `"none"` | Order rows by their total. |
| `domain` | `[number, number]` |  | Fix the ends of the colour scale. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Missing cells (cohort triangle)

```tsx
import { Heatmap } from "insightcharts";

const data = [
  { cohort: "Jan cohort", month: "M0", retained: 1 },
  { cohort: "Jan cohort", month: "M1", retained: 0.64 },
  { cohort: "Jan cohort", month: "M2", retained: 0.58 },
  { cohort: "Jan cohort", month: "M3", retained: 0.49 },
  { cohort: "Jan cohort", month: "M4", retained: 0.46 },
  { cohort: "Jan cohort", month: "M5", retained: 0.41 },
  { cohort: "Jan cohort", month: "M6", retained: 0.36 },
  { cohort: "Jan cohort", month: "M7", retained: 0.31 },
  // ... 28 more rows
];

<Heatmap
  data={data}
  x="month"
  y="cohort"
  value="retained"
  format="percent"
  title="Share of each signup cohort still active"
  subtitle="By months since signup, January to August cohorts"
  note="Illustrative data. Hatched cells have not happened yet."
/>
```

#### Diverging around zero

```tsx
import { Heatmap } from "insightcharts";

const data = [
  { region: "Arctic", decade: "1900s", anomaly: -1.51 },
  { region: "Arctic", decade: "1910s", anomaly: -1.14 },
  { region: "Arctic", decade: "1920s", anomaly: -0.92 },
  { region: "Arctic", decade: "1930s", anomaly: -0.94 },
  { region: "Arctic", decade: "1940s", anomaly: -0.45 },
  { region: "Arctic", decade: "1950s", anomaly: 0.02 },
  { region: "Arctic", decade: "1960s", anomaly: 0.02 },
  { region: "Arctic", decade: "1970s", anomaly: 0.47 },
  // ... 88 more rows
];

<Heatmap
  data={data}
  x="decade"
  y="region"
  value="anomaly"
  diverging
  format="signed"
  title="Temperature anomaly by region and decade, 1900s to 2010s"
  subtitle="Difference from the 20th-century mean, °C"
  note="Illustrative data"
/>
```

#### Stress: 18 by 24, highlighted row, a gap

```tsx
import { Heatmap } from "insightcharts";

const data = [
  { station: "Station 01", hour: "00:00", trips: 1 },
  { station: "Station 01", hour: "01:00", trips: 0 },
  { station: "Station 01", hour: "02:00", trips: 2 },
  { station: "Station 01", hour: "03:00", trips: 1 },
  { station: "Station 01", hour: "04:00", trips: 2 },
  { station: "Station 01", hour: "05:00", trips: 6 },
  { station: "Station 01", hour: "06:00", trips: 18 },
  { station: "Station 01", hour: "07:00", trips: 35 },
  // ... 420 more rows
];

<Heatmap
  data={data}
  x="hour"
  y="station"
  value="trips"
  highlight="Station 18"
  height={460}
  title="Trips started per hour by station"
  subtitle="Weekday average, 18 stations. Station 18 is highlighted. Station 08 has no data from 10:00 to 13:00."
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/heatmap.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/heatmap.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Histogram (`histogram`)

> Bins a numeric field and shows how many rows fall in each bin, as touching bars on a continuous axis.

- Component: `Histogram` (import from `insightcharts`)
- Spec type: `"histogram"`
- Level: atom. Category: distribution.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Showing the shape of a distribution for one numeric variable with roughly 50 rows or more: its centre, spread, skew, gaps and multiple peaks.

### Avoid

Comparing distributions across several groups (use box-plot or beeswarm-chart); under about 50 rows, where every observation can be shown (use strip-plot or beeswarm-chart); counts by category (use bar-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/histogram
```

The file lands at `components/insightcharts/atoms/histogram.tsx`. `@insightcharts/histogram-demo` adds a ready-made example next to it.

### Usage

```tsx
import { Histogram } from "insightcharts";

const data = [
  { minutes: 14 },
  { minutes: 18 },
  { minutes: 18 },
  { minutes: 19 },
  { minutes: 20 },
  { minutes: 21 },
  { minutes: 21 },
  { minutes: 22 },
  { minutes: 23 },
  { minutes: 23 },
  { minutes: 23 },
  { minutes: 23 },
  { minutes: 24 },
  { minutes: 25 },
  { minutes: 25 },
  { minutes: 27 },
  { minutes: 27 },
  { minutes: 27 },
  { minutes: 27 },
  { minutes: 27 },
  { minutes: 28 },
  { minutes: 28 },
  { minutes: 28 },
  { minutes: 28 },
  { minutes: 29 },
  { minutes: 29 },
  { minutes: 29 },
  { minutes: 29 },
  { minutes: 30 },
  { minutes: 31 },
  { minutes: 31 },
  { minutes: 31 },
  { minutes: 31 },
  { minutes: 32 },
  { minutes: 32 },
  { minutes: 32 },
  { minutes: 32 },
  { minutes: 32 },
  { minutes: 33 },
  { minutes: 33 },
  { minutes: 33 },
  { minutes: 34 },
  { minutes: 34 },
  { minutes: 34 },
  { minutes: 34 },
  { minutes: 35 },
  { minutes: 35 },
  { minutes: 35 },
  { minutes: 35 },
  { minutes: 35 },
  { minutes: 35 },
  { minutes: 35 },
  { minutes: 36 },
  { minutes: 36 },
  { minutes: 36 },
  { minutes: 37 },
  { minutes: 37 },
  { minutes: 37 },
  { minutes: 38 },
  { minutes: 38 },
  { minutes: 40 },
  { minutes: 40 },
  { minutes: 40 },
  { minutes: 40 },
  { minutes: 41 },
  { minutes: 41 },
  { minutes: 42 },
  { minutes: 42 },
  { minutes: 42 },
  { minutes: 43 },
  { minutes: 45 },
  { minutes: 45 },
  { minutes: 46 },
  { minutes: 47 },
  { minutes: 47 },
  { minutes: 48 },
  { minutes: 48 },
  { minutes: 49 },
  { minutes: 49 },
  { minutes: 51 },
  { minutes: 51 },
  { minutes: 54 },
  { minutes: 54 },
  { minutes: 55 },
  { minutes: 57 },
  { minutes: 57 },
  { minutes: 59 },
  { minutes: 59 },
  { minutes: 61 },
  { minutes: 66 },
];

<Histogram
  data={data}
  value="minutes"
  step={5}
  median
  countLabel="Commuters"
  format="{value} min"
  title="The median commute of 90 surveyed employees was 34.5 minutes"
  subtitle="One-way commute time, in 5-minute bins"
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "histogram",
  "data": [
    { "minutes": 14 },
    { "minutes": 18 },
    { "minutes": 18 },
    { "minutes": 19 },
    { "minutes": 20 },
    { "minutes": 21 },
    { "minutes": 21 },
    { "minutes": 22 },
    { "minutes": 23 },
    { "minutes": 23 },
    { "minutes": 23 },
    { "minutes": 23 },
    { "minutes": 24 },
    { "minutes": 25 },
    { "minutes": 25 },
    { "minutes": 27 },
    { "minutes": 27 },
    { "minutes": 27 },
    { "minutes": 27 },
    { "minutes": 27 },
    { "minutes": 28 },
    { "minutes": 28 },
    { "minutes": 28 },
    { "minutes": 28 },
    { "minutes": 29 },
    { "minutes": 29 },
    { "minutes": 29 },
    { "minutes": 29 },
    { "minutes": 30 },
    { "minutes": 31 },
    { "minutes": 31 },
    { "minutes": 31 },
    { "minutes": 31 },
    { "minutes": 32 },
    { "minutes": 32 },
    { "minutes": 32 },
    { "minutes": 32 },
    { "minutes": 32 },
    { "minutes": 33 },
    { "minutes": 33 },
    { "minutes": 33 },
    { "minutes": 34 },
    { "minutes": 34 },
    { "minutes": 34 },
    { "minutes": 34 },
    { "minutes": 35 },
    { "minutes": 35 },
    { "minutes": 35 },
    { "minutes": 35 },
    { "minutes": 35 },
    { "minutes": 35 },
    { "minutes": 35 },
    { "minutes": 36 },
    { "minutes": 36 },
    { "minutes": 36 },
    { "minutes": 37 },
    { "minutes": 37 },
    { "minutes": 37 },
    { "minutes": 38 },
    { "minutes": 38 },
    { "minutes": 40 },
    { "minutes": 40 },
    { "minutes": 40 },
    { "minutes": 40 },
    { "minutes": 41 },
    { "minutes": 41 },
    { "minutes": 42 },
    { "minutes": 42 },
    { "minutes": 42 },
    { "minutes": 43 },
    { "minutes": 45 },
    { "minutes": 45 },
    { "minutes": 46 },
    { "minutes": 47 },
    { "minutes": 47 },
    { "minutes": 48 },
    { "minutes": 48 },
    { "minutes": 49 },
    { "minutes": 49 },
    { "minutes": 51 },
    { "minutes": 51 },
    { "minutes": 54 },
    { "minutes": 54 },
    { "minutes": 55 },
    { "minutes": 57 },
    { "minutes": 57 },
    { "minutes": 59 },
    { "minutes": 59 },
    { "minutes": 61 },
    { "minutes": 66 }
  ],
  "value": "minutes",
  "step": 5,
  "median": true,
  "countLabel": "Commuters",
  "format": "{value} min",
  "title": "The median commute of 90 surveyed employees was 34.5 minutes",
  "subtitle": "One-way commute time, in 5-minute bins",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `string` |  | Numeric field to bin. |
| `bins` | `number` |  | Approximate number of bins; the width is rounded to a tidy step. Default: from the row count. |
| `step` | `number` |  | Exact bin width in value units. Overrides `bins`. |
| `median` | `boolean` | `false` | Vertical marker at the median. |
| `mean` | `boolean` | `false` | Vertical marker at the mean. |
| `normalize` | `boolean` | `false` | Share of rows per bin instead of a count. |
| `countLabel` | `string` |  | Title for the count axis, e.g. "Runners". |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Large sample, 10-minute bins

```tsx
import { Histogram } from "insightcharts";

const data = [
  { minutes: 321 },
  { minutes: 263 },
  { minutes: 285 },
  { minutes: 310 },
  { minutes: 274 },
  { minutes: 250 },
  { minutes: 285 },
  { minutes: 266 },
  // ... 1192 more rows
];

<Histogram
  data={data}
  value="minutes"
  step={10}
  median
  countLabel="Finishers"
  format="{value} min"
  title="Finish times of 1,200 marathon runners"
  subtitle="Minutes, in 10-minute bins. The line marks the median."
  note="Illustrative data"
/>
```

#### Skewed, with mean and median

```tsx
import { Histogram } from "insightcharts";

const data = [
  { income: 31300 },
  { income: 35600 },
  { income: 15500 },
  { income: 14300 },
  { income: 48200 },
  { income: 25500 },
  { income: 18000 },
  { income: 69600 },
  // ... 2987 more rows
];

<Histogram
  data={data}
  value="income"
  step={10000}
  mean
  median
  normalize
  format="currency:USD"
  countLabel="Share of households"
  title="Household income distribution"
  subtitle="Share of households in each $10,000 bin, with the mean and the median marked"
  note="Illustrative data"
/>
```

#### Two peaks

```tsx
import { Histogram } from "insightcharts";

const data = [
  { wait: 51 },
  { wait: 72 },
  { wait: 76 },
  { wait: 60 },
  { wait: 82 },
  { wait: 88 },
  { wait: 52 },
  { wait: 82 },
  // ... 264 more rows
];

<Histogram
  data={data}
  value="wait"
  bins={20}
  countLabel="Eruptions"
  format="{value} min"
  annotations={[{ type: "band", axis: "x", from: 62, to: 70, label: "Rarely" }]}
  title="Waiting time between Old Faithful eruptions"
  subtitle="Minutes between eruptions, 272 observations"
  note="Illustrative data modelled on the Old Faithful geyser dataset"
/>
```

#### Stress: few rows, many bins

```tsx
import { Histogram } from "insightcharts";

const data = [
  { days: 2 },
  { days: 3 },
  { days: 3 },
  { days: 4 },
  { days: 4 },
  { days: 4 },
  { days: 5 },
  { days: 5 },
  // ... 7 more rows
];

<Histogram
  data={data}
  value="days"
  step={1}
  median
  countLabel="Tickets"
  format="{value}d"
  title="11 of 15 support tickets closed within 7 days"
  subtitle="Days to resolution, 15 support tickets"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/histogram.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/histogram.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Icon array grid (`icon-array-grid`)

> Compares many counts as a grid of labelled tiles, each holding an array of N icons with its name and number.

- Component: `IconArrayGrid` (import from `insightcharts`)
- Spec type: `"icon-array-grid"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Counts of up to about 150 in 4 to 24 categories, especially rates per 100 or per 1,000: cars per 100 households in 12 districts. Set `total` so every tile shows the same full array with the uncounted icons as ghosts.

### Avoid

Counts in the thousands (use unit-blocks); two to six categories where one row of icons each is enough (use pictogram-chart); values that need precise comparison or ranking (use block-bar or bar-chart); one share of one whole (use waffle-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/icon-array-grid
```

The file lands at `components/insightcharts/atoms/icon-array-grid.tsx`. `@insightcharts/icon-array-grid-demo` adds a ready-made example next to it.

### Usage

```tsx
import { IconArrayGrid } from "insightcharts";

const data = [
  { district: "Ashby", cars: 118 },
  { district: "Brook End", cars: 104 },
  { district: "Castle Hill", cars: 97 },
  { district: "Dockside", cars: 41 },
  { district: "Eastfield", cars: 88 },
  { district: "Fairmile", cars: 126 },
  { district: "Greenway", cars: 73 },
  { district: "Hollins", cars: 110 },
  { district: "Old Town", cars: 36 },
  { district: "Priory", cars: 92 },
  { district: "Riverside", cars: 58 },
  { district: "Station Quarter", cars: 29 },
];

<IconArrayGrid
  data={data}
  name="district"
  value="cars"
  icon="car"
  unitLabel="1 car per 100 households"
  columns={4}
  title="Fairmile had 126 cars per 100 households in 2025"
  subtitle="Cars per 100 households in 12 districts of Port Aldwin, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional city"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "icon-array-grid",
  "data": [
    { "district": "Ashby", "cars": 118 },
    { "district": "Brook End", "cars": 104 },
    { "district": "Castle Hill", "cars": 97 },
    { "district": "Dockside", "cars": 41 },
    { "district": "Eastfield", "cars": 88 },
    { "district": "Fairmile", "cars": 126 },
    { "district": "Greenway", "cars": 73 },
    { "district": "Hollins", "cars": 110 },
    { "district": "Old Town", "cars": 36 },
    { "district": "Priory", "cars": 92 },
    { "district": "Riverside", "cars": 58 },
    { "district": "Station Quarter", "cars": 29 }
  ],
  "name": "district",
  "value": "cars",
  "icon": "car",
  "unitLabel": "1 car per 100 households",
  "columns": 4,
  "title": "Fairmile had 126 cars per 100 households in 2025",
  "subtitle": "Cars per 100 households in 12 districts of Port Aldwin, 2025",
  "source": "Illustrative data",
  "note": "Invented figures for a fictional city"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Category field: one tile per row. |
| `value` (required) | `string` |  | Value field: the count each tile shows. |
| `unit` | `number` | `1` | Units per icon. |
| `unitLabel` | `string` |  | What one icon stands for, for the key line, e.g. "1 car". |
| `total` | `number` |  | Draw every tile out of this many units, with uncounted icons as ghosts: 100 for a rate per 100. |
| `icon` | `IconName \| "path://..."` | `"circle"` | Built-in icon name or a custom single SVG path. |
| `perRow` | `number` | `10` | Icons per line inside a tile. |
| `columns` | `number` |  | Most tiles per line. Default: as many as fit at a readable size. Narrow containers use fewer. |
| `sort` | `"none" \| "asc" \| "desc"` | `"none"` | Order of the tiles. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Out of 100, with ghosts, highlight, click to select

```tsx
import { IconArrayGrid } from "insightcharts";

const data = [
  { ward: "Abbey", voted: 71 },
  { ward: "Bridge", voted: 64 },
  { ward: "Canal", voted: 38 },
  { ward: "Deanery", voted: 59 },
  { ward: "Elm Park", voted: 67 },
  { ward: "Foundry", voted: 44 },
  { ward: "Grange", voted: 76 },
  { ward: "Haymarket", voted: 52 },
];

<IconArrayGrid
  data={data}
  name="ward"
  value="voted"
  total={100}
  icon="person"
  perRow={20}
  unitLabel="1 in every 100 registered voters"
  format="{value}%"
  highlight="Canal"
  select
  title="38 in every 100 registered voters in Canal ward voted in 2025"
  subtitle="Turnout at the 2025 council election by ward, voters per 100 registered"
  source="Illustrative data"
  note="Invented figures for a fictional council"
/>
```

#### Squares, five per line, sorted

```tsx
import { IconArrayGrid } from "insightcharts";

const data = [
  { club: "Harriers", medals: 23 },
  { club: "Lakeside", medals: 17 },
  { club: "Northgate", medals: 31 },
  { club: "Old Mill", medals: 8 },
  { club: "Quayside", medals: 12 },
  { club: "Westbrook", medals: 4 },
];

<IconArrayGrid
  data={data}
  name="club"
  value="medals"
  icon="square"
  perRow={5}
  columns={6}
  sort="desc"
  unitLabel="1 medal"
  title="Northgate won 31 medals at the 2025 county championships"
  subtitle="Medals won by club, 2025 county athletics championships"
  source="Illustrative data"
  note="Invented figures"
/>
```

#### Stress: 24 tiles, long names, uneven counts

```tsx
import { IconArrayGrid } from "insightcharts";

const data = [
  { area: "Aldermoor and the northern villages", points: 142 },
  { area: "Barrow", points: 3 },
  { area: "Charnwood Forest", points: 87 },
  { area: "Denby", points: 0 },
  { area: "East Leake and Stanford", points: 61 },
  { area: "Fosse", points: 118 },
  { area: "Great Glen", points: 24 },
  { area: "Hathern", points: 9 },
  // ... 16 more rows
];

<IconArrayGrid
  data={data}
  name="area"
  value="points"
  icon="bolt"
  perRow={15}
  unitLabel="1 public charge point"
  title="Loughborough Central had 150 public charge points in 2025"
  subtitle="Public electric vehicle charge points by area, 2025"
  source="Illustrative data"
  note="Invented figures"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/icon-array-grid.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/icon-array-grid.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Icon stat (`icon-stat`)

> A "1 in 4"-style statement: a row or grid of simple glyphs with some filled, and the sentence they illustrate.

- Component: `IconStat` (import from `insightcharts`)
- Spec type: `"icon-stat"`
- Level: atom. Category: figure.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

A single proportion that is easier to read as people or units than as a percentage: 1 in 4, 3 in 10, 37 of 100. Round to a small denominator first.

### Avoid

Comparing several proportions (use `bar-chart`), precise percentages (use `big-number`), or fractions that need more than 100 units.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/icon-stat
```

The file lands at `components/insightcharts/atoms/icon-stat.tsx`. `@insightcharts/icon-stat-demo` adds a ready-made example next to it.

### Usage

```tsx
import { IconStat } from "insightcharts";

<IconStat
  icon="person"
  count={1}
  total={4}
  text="households could not cover an unexpected bill of €500 without borrowing."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "icon-stat",
  "icon": "person",
  "count": 1,
  "total": 4,
  "text": "households could not cover an unexpected bill of €500 without borrowing."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `count` (required) | `number` |  | How many glyphs are filled. |
| `total` | `number` | `10` | How many glyphs are drawn. Capped at 100. |
| `text` | `string` |  | The sentence completing the figure. |
| `children` | `ReactNode` |  | JSX alternative to `text`. |
| `value` | `string \| false` |  | The figure as words. Defaults to "{count} in {total}"; `false` hides it. |
| `icon` | `"circle" \| "person" \| "square" \| IconName` | `"circle"` | Glyph per unit. Filled units are solid, the rest outlined. Any other icon name from `core/icons.ts` also works; its unfilled units are faded instead of outlined. |
| `columns` | `number` |  | Glyphs per row. Defaults to `total`, at most 10. |
| `size` | `number` |  | Glyph height in px; shrinks to fit narrow containers. |
| `tone` | `"accent" \| "positive" \| "negative" \| "neutral"` | `"accent"` | Fill colour by meaning. |
| `align` | `"left" \| "center"` | `"left"` | Alignment. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [poster](https://insightcharts.dev/llms/poster.md), [proportion-statement](https://insightcharts.dev/llms/proportion-statement.md), [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md), [explainer](https://insightcharts.dev/llms/explainer.md)

### More examples

#### Circles, 3 in 10

```tsx
import { IconStat } from "insightcharts";

<IconStat count={3} total={10} text="new cars sold in Europe in 2024 had a plug." />
```

#### Grid of 100

```tsx
import { IconStat } from "insightcharts";

<IconStat
  count={37}
  total={100}
  icon="square"
  value="37%"
  text="of the national grid's transmission lines are more than 40 years old."
  tone="negative"
/>
```

#### People, centered, custom value

```tsx
import { IconStat } from "insightcharts";

<IconStat
  icon="person"
  count={7}
  total={10}
  align="center"
  value="Seven in ten"
  text="renters say they have delayed switching the heating on."
  tone="neutral"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/icon-stat.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/icon-stat.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Legend key (`legend-key`)

> A standalone colour key: categorical swatches, or a sequential/diverging ramp with end labels.

- Component: `LegendKey` (import from `insightcharts`)
- Spec type: `"legend-key"`
- Level: atom. Category: figure.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

When several charts (small multiples, a map and a bar chart, a dashboard row) share one colour encoding, show the key once above them and turn their own legends off.

### Avoid

A single chart: its built-in legend or, better, direct labels already do this. Do not list more than eight categories.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/legend-key
```

The file lands at `components/insightcharts/atoms/legend-key.tsx`. `@insightcharts/legend-key-demo` adds a ready-made example next to it.

### Usage

```tsx
import { LegendKey } from "insightcharts";

<LegendKey
  title="Source of electricity"
  items={["Solar", "Wind", "Hydro", "Gas", { label: "Other", muted: true }]}
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "legend-key",
  "title": "Source of electricity",
  "items": ["Solar", "Wind", "Hydro", "Gas", { "label": "Other", "muted": true }]
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `scale` | `"categorical" \| "sequential" \| "diverging"` |  | Defaults to `categorical` when `items` is given, otherwise `sequential`. |
| `items` | `(string \| { label, color?, index?, shape?, muted? })[]` |  | Categorical entries. Colours come from the theme's categorical order by position (or `index`) unless given. |
| `labels` | `string[]` |  | Ramp end labels: `[low, high]` or `[low, middle, high]`. |
| `colors` | `string[]` |  | Ramp colours, low to high. Defaults to the theme's sequential or diverging ramp. |
| `stepped` | `boolean` | `false` | Discrete steps instead of a continuous gradient, for binned scales. |
| `title` | `string` |  | What the key encodes. |
| `shape` | `"square" \| "line" \| "dot"` | `"square"` | Default swatch shape: match the marks. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Categorical layout. |
| `width` | `number` | `240` | Ramp width in px, capped at the container. |
| `align` | `"left" \| "center"` | `"left"` | Alignment within the container. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [small-multiple-grid](https://insightcharts.dev/llms/small-multiple-grid.md)

### More examples

#### Sequential ramp

```tsx
import { LegendKey } from "insightcharts";

<LegendKey
  scale="sequential"
  title="Share of electricity from renewables"
  labels={["0%", "100%"]}
/>
```

#### Diverging, stepped

```tsx
import { LegendKey } from "insightcharts";

<LegendKey
  scale="diverging"
  stepped
  title="Change in house prices, 2019 to 2024"
  labels={["−20%", "No change", "+20%"]}
  width={300}
/>
```

#### Lines, vertical, explicit order

```tsx
import { LegendKey } from "insightcharts";

<LegendKey
  orientation="vertical"
  shape="line"
  items={[
    { label: "Germany", index: 0 },
    { label: "Spain", index: 3 },
    { label: "EU average", muted: true },
  ]}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/legend-key.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/legend-key.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Line chart (`line-chart`)

> Shows how one or more values change over time or another ordered dimension.

- Component: `LineChart` (import from `insightcharts`)
- Spec type: `"line-chart"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Trends over time with roughly 5 or more points; comparing the trajectories of a few series; one highlighted series against many context series.

### Avoid

Unordered categories (use bar-chart); only two time points (use slope-chart); more than about 6 equally important lines (use small-multiples).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/line-chart
```

The file lands at `components/insightcharts/atoms/line-chart.tsx`. `@insightcharts/line-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { LineChart } from "insightcharts";

const data = [
  { year: "2019", solar: 2.7, wind: 5.3 },
  { year: "2020", solar: 3.2, wind: 5.9 },
  { year: "2021", solar: 3.7, wind: 6.5 },
  { year: "2022", solar: 4.6, wind: 7.3 },
  { year: "2023", solar: 5.5, wind: 7.8 },
];

<LineChart
  data={data}
  x="year"
  y={["solar", "wind"]}
  format="{value}%"
  title="Solar's share rose from 2.7% to 5.5% between 2019 and 2023"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "line-chart",
  "data": [
    { "year": "2019", "solar": 2.7, "wind": 5.3 },
    { "year": "2020", "solar": 3.2, "wind": 5.9 },
    { "year": "2021", "solar": 3.7, "wind": 6.5 },
    { "year": "2022", "solar": 4.6, "wind": 7.3 },
    { "year": "2023", "solar": 5.5, "wind": 7.8 }
  ],
  "x": "year",
  "y": ["solar", "wind"],
  "format": "{value}%",
  "title": "Solar's share rose from 2.7% to 5.5% between 2019 and 2023"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Time or ordered category field. ISO dates are placed on a true time axis. |
| `y` (required) | `string \| string[]` |  | Value field, or several (one line each). |
| `series` | `string` |  | Field that splits rows into lines (long data). |
| `curve` | `"linear" \| "smooth" \| "step"` | `"linear"` | Line shape. |
| `area` | `boolean` | `false` | Light fill under the line; forces a zero baseline. |
| `endLabels` | `boolean` |  | Name each line at its end. Default: on for up to 6 lines. |
| `points` | `boolean` |  | Marker on every point. Default: on for 12 points or fewer. |
| `zero` | `boolean` | `false` | Start the value axis at zero. |
| `log` | `boolean` | `false` | Logarithmic value axis. |
| `names` | `Record<string, string>` |  | Display names for series keys. |
| `contextLabels` | `boolean \| string` | `false` | With `highlight`: name the grey context lines. `true` adds a muted end label to each when they all fit; a string such as `"Other cities"` adds one muted legend entry instead. On narrow charts the legend already lists every line. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [chart-callout](https://insightcharts.dev/llms/chart-callout.md), [chart-tabs](https://insightcharts.dev/llms/chart-tabs.md), [hero-figure](https://insightcharts.dev/llms/hero-figure.md), [linked-charts](https://insightcharts.dev/llms/linked-charts.md), [section](https://insightcharts.dev/llms/section.md), [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md), [executive-brief](https://insightcharts.dev/llms/executive-brief.md), [explainer](https://insightcharts.dev/llms/explainer.md), [report-page](https://insightcharts.dev/llms/report-page.md), [scorecard](https://insightcharts.dev/llms/scorecard.md), [story-deck](https://insightcharts.dev/llms/story-deck.md), [timeline-story](https://insightcharts.dev/llms/timeline-story.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Highlight with named context lines

```tsx
import { LineChart } from "insightcharts";

const data = [
  { year: "2015", city: "Lagos", share: 20.6 },
  { year: "2015", city: "Nairobi", share: 36 },
  { year: "2015", city: "Kampala", share: 13 },
  { year: "2015", city: "Addis", share: 6.6 },
  { year: "2016", city: "Lagos", share: 26.9 },
  { year: "2016", city: "Nairobi", share: 38.7 },
  { year: "2016", city: "Kampala", share: 16.6 },
  { year: "2016", city: "Addis", share: 14.5 },
  // ... 32 more rows
];

<LineChart
  data={data}
  x="year"
  y="share"
  series="city"
  highlight="Addis"
  contextLabels
  format="{value}%"
  title="Mobile money use in Addis rose from 6.6% in 2015 to 60.8% in 2024"
  subtitle="Share of households with a mobile money account. `contextLabels: true` names the grey lines in muted type."
  note="Illustrative data"
/>
```

#### Highlight, one legend entry for the rest, annotations near the right edge

```tsx
import { LineChart } from "insightcharts";

const data = [
  { year: "2015", city: "Lagos", share: 20.6 },
  { year: "2015", city: "Nairobi", share: 36 },
  { year: "2015", city: "Kampala", share: 13 },
  { year: "2015", city: "Addis", share: 6.6 },
  { year: "2016", city: "Lagos", share: 26.9 },
  { year: "2016", city: "Nairobi", share: 38.7 },
  { year: "2016", city: "Kampala", share: 16.6 },
  { year: "2016", city: "Addis", share: 14.5 },
  // ... 32 more rows
];

<LineChart
  data={data}
  x="year"
  y="share"
  series="city"
  highlight="Addis"
  contextLabels="Other cities"
  annotations={[
    { type: "line", axis: "y", value: 60, label: "National target" },
    { type: "point", x: "2023", y: 49.5, label: "Agent network\nreaches every district" },
  ]}
  format="{value}%"
  title="Addis reached the 60% national target in 2024"
  subtitle="Households with a mobile money account"
  note="Illustrative data"
/>
```

#### Stress: six lines converge

```tsx
import { LineChart } from "insightcharts";

const data = [
  { year: "2015", Lagos: 20.6, Nairobi: 36, Accra: 26.6, Dakar: 39.6, Kampala: 13, Addis: 6.6 },
  { year: "2016", Lagos: 26.9, Nairobi: 38.7, Accra: 32.2, Dakar: 43.6, Kampala: 16.6, Addis: 14.5 },
  { year: "2017", Lagos: 31.9, Nairobi: 39.2, Accra: 36.4, Dakar: 46.2, Kampala: 17.9, Addis: 21 },
  { year: "2018", Lagos: 34.1, Nairobi: 42.5, Accra: 37.8, Dakar: 46, Kampala: 22, Addis: 24.7 },
  { year: "2019", Lagos: 38.3, Nairobi: 47.3, Accra: 41.3, Dakar: 47.9, Kampala: 27.6, Addis: 30.4 },
  { year: "2020", Lagos: 44.9, Nairobi: 48.9, Accra: 47.1, Dakar: 52.1, Kampala: 30.1, Addis: 38.5 },
  { year: "2021", Lagos: 48.7, Nairobi: 49.8, Accra: 50.2, Dakar: 53.6, Kampala: 31.8, Addis: 43.9 },
  { year: "2022", Lagos: 50.9, Nairobi: 54.1, Accra: 51.7, Dakar: 53.5, Kampala: 37, Addis: 47.7 },
  // ... 2 more rows
];

<LineChart
  data={data}
  x="year"
  y={["Lagos", "Nairobi", "Accra", "Dakar", "Kampala", "Addis"]}
  format="{value}%"
  title="Five of six cities had between 58.8% and 61% of households using mobile money in 2024"
  subtitle="Households with a mobile money account"
  note="Illustrative data"
/>
```

#### Long format with highlight

```tsx
import { LineChart } from "insightcharts";

const data = [
  { year: "2015", city: "Lagos", share: 20.6 },
  { year: "2015", city: "Nairobi", share: 36 },
  { year: "2015", city: "Kampala", share: 13 },
  { year: "2015", city: "Addis", share: 6.6 },
  { year: "2016", city: "Lagos", share: 26.9 },
  { year: "2016", city: "Nairobi", share: 38.7 },
  { year: "2016", city: "Kampala", share: 16.6 },
  { year: "2016", city: "Addis", share: 14.5 },
  // ... 32 more rows
];

<LineChart
  data={data}
  x="year"
  y="share"
  series="city"
  highlight="Addis"
  format="{value}%"
  title="Mobile money use in Addis rose from 6.6% in 2015 to 60.8% in 2024"
  subtitle="Households with a mobile money account"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/line-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/line-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Lollipop chart (`lollipop-chart`)

> Ranks categories with a dot on a thin stem from zero, or as a stemless dot plot on a free scale.

- Component: `LollipopChart` (import from `insightcharts`)
- Spec type: `"lollipop-chart"`
- Level: atom. Category: comparison.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Rankings of 8 to 30 categories where bars would be too heavy; dot plot mode when the values sit far from zero and the differences between them matter, or to compare a few series per row.

### Avoid

Fewer than about 6 categories or part-to-whole stacks (use bar-chart); exactly two values per row where the difference between them matters (use dumbbell-chart); change over time (use line-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/lollipop-chart
```

The file lands at `components/insightcharts/atoms/lollipop-chart.tsx`. `@insightcharts/lollipop-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { LollipopChart } from "insightcharts";

const data = [
  { country: "Netherlands", share: 27 },
  { country: "Denmark", share: 19 },
  { country: "Germany", share: 10 },
  { country: "Sweden", share: 9 },
  { country: "Japan", share: 8 },
  { country: "France", share: 4 },
  { country: "United Kingdom", share: 2 },
  { country: "United States", share: 1 },
];

<LollipopChart
  data={data}
  x="country"
  y="share"
  format="{value}%"
  height={300}
  title="27% of trips in the Netherlands are made by bike"
  subtitle="Share of all trips made by bicycle"
  source="National travel surveys, latest available year (rounded)"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "lollipop-chart",
  "data": [
    { "country": "Netherlands", "share": 27 },
    { "country": "Denmark", "share": 19 },
    { "country": "Germany", "share": 10 },
    { "country": "Sweden", "share": 9 },
    { "country": "Japan", "share": 8 },
    { "country": "France", "share": 4 },
    { "country": "United Kingdom", "share": 2 },
    { "country": "United States", "share": 1 }
  ],
  "x": "country",
  "y": "share",
  "format": "{value}%",
  "height": 300,
  "title": "27% of trips in the Netherlands are made by bike",
  "subtitle": "Share of all trips made by bicycle",
  "source": "National travel surveys, latest available year (rounded)",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Category field. |
| `y` (required) | `string \| string[]` |  | Value field. Several fields draw several dots per row (dot plot). |
| `series` | `string` |  | Field that splits rows into series (long data). Forces the dot plot. |
| `stem` | `boolean` | `true` | Stem from zero. `false` draws a dot plot whose scale need not start at zero. |
| `orientation` | `"auto" \| "horizontal" \| "vertical"` | `"auto"` | Horizontal for rankings, vertical for dates. |
| `sort` | `"none" \| "asc" \| "desc"` |  | Row order. Default: descending for rankings, data order for dates. |
| `labels` | `boolean` |  | Value beside each dot. Default: on for one series of up to 16 rows. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Dot plot on a non-zero scale, highlighted

```tsx
import { LollipopChart } from "insightcharts";

const data = [
  { country: "Japan", years: 84.1 },
  { country: "Switzerland", years: 83.9 },
  { country: "Spain", years: 83.3 },
  { country: "Italy", years: 83 },
  { country: "Sweden", years: 83.1 },
  { country: "France", years: 82.5 },
  { country: "Canada", years: 81.6 },
  { country: "Germany", years: 81.2 },
  // ... 2 more rows
];

<LollipopChart
  data={data}
  x="country"
  y="years"
  stem={false}
  highlight="United States"
  format="decimal:1"
  title="Life expectancy in the United States was 78.4 years in 2023"
  subtitle="Life expectancy at birth, years, 2023. The scale does not start at zero."
  source="OECD Health Statistics (rounded)"
  note="Figures are approximate, for illustration"
/>
```

#### Long format, three dots per row

```tsx
import { LollipopChart } from "insightcharts";

const data = [
  { job: "Nurses", age: "Over 55", trust: 82 },
  { job: "Nurses", age: "35 to 54", trust: 71 },
  { job: "Nurses", age: "Under 35", trust: 64 },
  { job: "Teachers", age: "Over 55", trust: 74 },
  { job: "Teachers", age: "35 to 54", trust: 66 },
  { job: "Teachers", age: "Under 35", trust: 58 },
  { job: "Police officers", age: "Over 55", trust: 61 },
  { job: "Police officers", age: "35 to 54", trust: 55 },
  // ... 10 more rows
];

<LollipopChart
  data={data}
  x="job"
  y="trust"
  series="age"
  format="{value}%"
  height={300}
  title="82% of people over 55 trust nurses"
  subtitle="Share who say they trust each profession, by age group"
  note="Illustrative figures."
/>
```

#### Vertical, over time

```tsx
import { LollipopChart } from "insightcharts";

const data = [
  { month: "2024-01", launches: 18 },
  { month: "2024-02", launches: 15 },
  { month: "2024-03", launches: 22 },
  { month: "2024-04", launches: 21 },
  { month: "2024-05", launches: 24 },
  { month: "2024-06", launches: 19 },
  { month: "2024-07", launches: 17 },
  { month: "2024-08", launches: 23 },
  // ... 4 more rows
];

<LollipopChart
  data={data}
  x="month"
  y="launches"
  height={280}
  title="There were 28 orbital launch attempts in December 2024"
  subtitle="Orbital launch attempts worldwide per month, 2024"
  note="Illustrative figures."
/>
```

#### Stress: 26 rows with long names

```tsx
import { LollipopChart } from "insightcharts";

const data = [
  { occupation: "Community and social service occupations", openings: 960 },
  { occupation: "Healthcare practitioners and technical occupations", openings: 1013 },
  { occupation: "Education, training and library occupations", openings: 928 },
  { occupation: "Computer and mathematical occupations", openings: 981 },
  { occupation: "Architecture and engineering occupations", openings: 896 },
  { occupation: "Life, physical and social science occupations", openings: 811 },
  { occupation: "Legal occupations", openings: 864 },
  { occupation: "Business and financial operations", openings: 779 },
  // ... 18 more rows
];

<LollipopChart
  data={data}
  x="occupation"
  y="openings"
  labels={false}
  format="compact"
  title="Community and social service occupations have 960,000 projected openings a year"
  subtitle="Projected annual job openings, thousands"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/lollipop-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/lollipop-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Nested shares (`nested-shares`)

> Shows several shares of the same whole, such as one share at five dates, as outlines nested from one corner of a square, each enclosing an area equal to its share.

- Component: `NestedShares` (import from `insightcharts`)
- Spec type: `"nested-shares"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

How much of one whole something was at 2 to 8 dates or in 2 to 8 categories, when the growth of a share is the point: bicycles made 4% of trips in 2005 and 27% in 2025.

### Avoid

Shares that are parts of each other and should add up (use waffle-chart or treemap); more than 8 items or precise reading of a trend (use line-chart); shares within a point or two of each other, where outlines coincide (use block-bar).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/nested-shares
```

The file lands at `components/insightcharts/atoms/nested-shares.tsx`. `@insightcharts/nested-shares-demo` adds a ready-made example next to it.

### Usage

```tsx
import { NestedShares } from "insightcharts";

const data = [
  { year: "2005", share: 4 },
  { year: "2010", share: 7 },
  { year: "2015", share: 12 },
  { year: "2020", share: 19 },
  { year: "2025", share: 27 },
];

<NestedShares
  data={data}
  name="year"
  value="share"
  format="{value}%"
  highlight="2025"
  wholeLabel="All trips in the city"
  title="Bicycles made 27% of trips in Port Aldwin in 2025"
  subtitle="Share of all trips made by bicycle, 2005 to 2025"
  source="Illustrative data"
  note="Invented figures for a fictional city"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "nested-shares",
  "data": [
    { "year": "2005", "share": 4 },
    { "year": "2010", "share": 7 },
    { "year": "2015", "share": 12 },
    { "year": "2020", "share": 19 },
    { "year": "2025", "share": 27 }
  ],
  "name": "year",
  "value": "share",
  "format": "{value}%",
  "highlight": "2025",
  "wholeLabel": "All trips in the city",
  "title": "Bicycles made 27% of trips in Port Aldwin in 2025",
  "subtitle": "Share of all trips made by bicycle, 2005 to 2025",
  "source": "Illustrative data",
  "note": "Invented figures for a fictional city"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Field naming each share: a period ("2025") or a category. |
| `value` (required) | `string` |  | Value field: each row's share of the whole. |
| `total` | `number` |  | The whole. Default: 1 when every value is at most 1, otherwise 100. |
| `wholeLabel` | `string` |  | What the outer square stands for, printed under it, e.g. "All trips". |
| `corner` | `"bottom-left" \| "top-left"` | `"bottom-left"` | The corner every outline grows from. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [count-poster](https://insightcharts.dev/llms/count-poster.md), [timeline-poster](https://insightcharts.dev/llms/timeline-poster.md)

### More examples

#### From the top corner, click to select

```tsx
import { NestedShares } from "insightcharts";

const data = [
  { year: "1995", share: 0.62 },
  { year: "2005", share: 0.48 },
  { year: "2015", share: 0.31 },
  { year: "2025", share: 0.14 },
];

<NestedShares
  data={data}
  name="year"
  value="share"
  format="percent"
  corner="top-left"
  select
  wholeLabel="All household waste"
  title="Landfill took 14% of household waste in 2025"
  subtitle="Share of household waste sent to landfill in Marlow County, 1995 to 2025"
  source="Illustrative data"
  note="Invented figures for a fictional county"
/>
```

#### By category, one highlighted

```tsx
import { NestedShares } from "insightcharts";

const data = [
  { group: "Aged 16 to 24", share: 71 },
  { group: "Aged 25 to 44", share: 58 },
  { group: "Aged 45 to 64", share: 33 },
  { group: "Aged 65 and over", share: 12 },
];

<NestedShares
  data={data}
  name="group"
  value="share"
  format="{value}%"
  highlight="Aged 65 and over"
  wholeLabel="Everyone in the age group"
  title="12% of people aged 65 and over paid by phone in 2025"
  subtitle="Share of each age group that made a contactless phone payment in the past month"
  source="Illustrative data"
  note="Invented survey figures"
/>
```

#### Stress: eight close shares, long names

```tsx
import { NestedShares } from "insightcharts";

const data = [
  { item: "First quarter of 2024", share: 2.1 },
  { item: "Second quarter of 2024", share: 2.4 },
  { item: "Third quarter of 2024", share: 3 },
  { item: "Fourth quarter of 2024", share: 3.2 },
  { item: "First quarter of 2025", share: 8.5 },
  { item: "Second quarter of 2025", share: 9.1 },
  { item: "Third quarter of 2025", share: 44 },
  { item: "Fourth quarter of 2025, provisional estimate", share: 46.5 },
];

<NestedShares
  data={data}
  name="item"
  value="share"
  format="{value}%"
  wholeLabel="All new car registrations"
  title="Electric cars were 46.5% of new registrations in the fourth quarter of 2025"
  subtitle="Battery electric share of new car registrations by quarter"
  source="Illustrative data"
  note="Invented figures"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/nested-shares.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/nested-shares.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Orbit chart (`orbit-chart`)

> Places items as dots on concentric rings round a centre, one ring per category, level or period, with a key that explains rings, angle and dot area.

- Component: `OrbitChart` (import from `insightcharts`)
- Spec type: `"orbit-chart"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A designed alternative to a table for 6 to about 40 named things grouped by distance, level or era from one centre: suppliers by tier, moons by planet-distance band, releases by decade, stakeholders by closeness. One item can be highlighted.

### Avoid

A numeric distance that must be read exactly (use strip-plot or scatter-chart); comparison of the dot values (use bar-chart); more than about 6 rings or 40 items (use data-table); hierarchy with sizes that add up (use treemap or circle-pack).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/orbit-chart
```

The file lands at `components/insightcharts/atoms/orbit-chart.tsx`. `@insightcharts/orbit-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { OrbitChart } from "insightcharts";

const data = [
  { supplier: "Halden Cells", tier: "Tier 1", spend: 84 },
  { supplier: "Orrin Motors", tier: "Tier 1", spend: 61 },
  { supplier: "Vale Castings", tier: "Tier 1", spend: 37 },
  { supplier: "Kestrel Wiring", tier: "Tier 2", spend: 22 },
  { supplier: "Brask Cathodes", tier: "Tier 2", spend: 48 },
  { supplier: "Lumen Glass", tier: "Tier 2", spend: 15 },
  { supplier: "Pell Magnets", tier: "Tier 2", spend: 29 },
  { supplier: "Tarn Lithium", tier: "Tier 3", spend: 33 },
  { supplier: "Iver Copper", tier: "Tier 3", spend: 19 },
  { supplier: "Sorrel Graphite", tier: "Tier 3", spend: 12 },
  { supplier: "Moss Resins", tier: "Tier 3", spend: 6 },
  { supplier: "Dunmore Nickel", tier: "Tier 3", spend: 26 },
];

<OrbitChart
  data={data}
  name="supplier"
  ring="tier"
  value="spend"
  format="${value}m"
  centerLabel="Car plant"
  highlight="Brask Cathodes"
  ringLabel="Tier 1 sells to the plant, each further ring sells to the ring inside it"
  sizeLabel="annual spend"
  title="Brask Cathodes is a tier 2 supplier with $48 million of annual spend"
  subtitle="12 suppliers to one car plant by supply-chain tier, annual spend in $ million"
  note="Illustrative figures for invented companies"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "orbit-chart",
  "data": [
    { "supplier": "Halden Cells", "tier": "Tier 1", "spend": 84 },
    { "supplier": "Orrin Motors", "tier": "Tier 1", "spend": 61 },
    { "supplier": "Vale Castings", "tier": "Tier 1", "spend": 37 },
    { "supplier": "Kestrel Wiring", "tier": "Tier 2", "spend": 22 },
    { "supplier": "Brask Cathodes", "tier": "Tier 2", "spend": 48 },
    { "supplier": "Lumen Glass", "tier": "Tier 2", "spend": 15 },
    { "supplier": "Pell Magnets", "tier": "Tier 2", "spend": 29 },
    { "supplier": "Tarn Lithium", "tier": "Tier 3", "spend": 33 },
    { "supplier": "Iver Copper", "tier": "Tier 3", "spend": 19 },
    { "supplier": "Sorrel Graphite", "tier": "Tier 3", "spend": 12 },
    { "supplier": "Moss Resins", "tier": "Tier 3", "spend": 6 },
    { "supplier": "Dunmore Nickel", "tier": "Tier 3", "spend": 26 }
  ],
  "name": "supplier",
  "ring": "tier",
  "value": "spend",
  "format": "${value}m",
  "centerLabel": "Car plant",
  "highlight": "Brask Cathodes",
  "ringLabel": "Tier 1 sells to the plant, each further ring sells to the ring inside it",
  "sizeLabel": "annual spend",
  "title": "Brask Cathodes is a tier 2 supplier with $48 million of annual spend",
  "subtitle": "12 suppliers to one car plant by supply-chain tier, annual spend in $ million",
  "note": "Illustrative figures for invented companies"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Name field: one dot per row. |
| `ring` (required) | `string` |  | Field naming the ring each dot sits on: a category, level or period. |
| `rings` | `string[]` |  | Ring order from the centre outward. Default: first appearance in the data. |
| `value` | `string` |  | Value field: dot area. Without it every dot is the same size. |
| `angle` | `string` |  | Numeric field that sets the angle round the ring. Without it dots are spaced evenly. |
| `angleDomain` | `[number, number]` | `[0, 360]` | Values of `angle` that map to a full turn, clockwise from 12 o'clock. |
| `ringLabel` | `string` |  | What the rings mean, for the key. Default: the `ring` field name. |
| `angleLabel` | `string` |  | What the angle means, for the key, e.g. "Clockwise from the top: month of launch". |
| `sizeLabel` | `string` |  | What dot area means, for the key. Default: the `value` field name. |
| `icon` | `string` |  | Icon in the centre disc: a built-in name or `path://`. |
| `centerLabel` | `string` |  | Short text in the centre disc, used when there is no `icon`. |
| `colorBy` | `"ring" \| "single"` | `"ring"` | A colour per ring, or the accent for every dot. |
| `showKey` | `boolean` | `true` | Show the key that explains rings, angle and dot area. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [radial-poster](https://insightcharts.dev/llms/radial-poster.md)

### More examples

#### Angle from the data, equal dots, click to select

```tsx
import { OrbitChart } from "insightcharts";

const data = [
  { event: "Founding charter", decade: "1970s", yearInDecade: 4, year: 1974 },
  { event: "First branch", decade: "1970s", yearInDecade: 8, year: 1978 },
  { event: "Mobile library", decade: "1980s", yearInDecade: 1, year: 1981 },
  { event: "Children's wing", decade: "1980s", yearInDecade: 6, year: 1986 },
  { event: "Card catalogue retired", decade: "1990s", yearInDecade: 3, year: 1993 },
  { event: "Public internet", decade: "1990s", yearInDecade: 6, year: 1996 },
  { event: "Archive fire", decade: "1990s", yearInDecade: 9, year: 1999 },
  { event: "E-book lending", decade: "2000s", yearInDecade: 8, year: 2008 },
  // ... 3 more rows
];

<OrbitChart
  data={data}
  name="event"
  ring="decade"
  angle="yearInDecade"
  angleDomain={[0, 10]}
  angleLabel="Clockwise from the top: year within the decade, 0 to 9"
  ringLabel="One ring per decade, 1970s innermost"
  colorBy="single"
  icon="house"
  highlight="Archive fire"
  select
  title="The city library has 11 milestones between 1974 and 2022"
  subtitle="Milestones of one public library by decade"
  note="Illustrative history of an invented library"
/>
```

#### Stress: 5 rings, 34 items, long names

```tsx
import { OrbitChart } from "insightcharts";

const data = [
  { body: "Tenants' and residents' association 1.1", level: "Household", members: 12 },
  { body: "Allotment society 1.2", level: "Household", members: 230 },
  { body: "Parish council 1.3", level: "Household", members: 55 },
  { body: "Food bank 1.4", level: "Household", members: 40 },
  { body: "Youth football league 1.5", level: "Household", members: 610 },
  { body: "Credit union 1.6", level: "Household", members: 8 },
  { body: "Food bank 2.1", level: "Street", members: 40 },
  { body: "Youth football league 2.2", level: "Street", members: 610 },
  // ... 26 more rows
];

<OrbitChart
  data={data}
  name="body"
  ring="level"
  value="members"
  sizeLabel="members"
  centerLabel="You"
  title="34 local bodies operate at five levels from household to region"
  subtitle="Civic bodies by the level they operate at, with members"
  note="Illustrative figures"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/orbit-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/orbit-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Pictogram chart (`pictogram-chart`)

> Compares quantities with rows of repeated icons, each icon standing for a fixed number of units.

- Component: `PictogramChart` (import from `insightcharts`)
- Spec type: `"pictogram-chart"`
- Level: atom. Category: comparison.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A few categories (2 to 6) of countable things, people, homes, vehicles, where making the quantity concrete matters more than reading precise values.

### Avoid

More than about 8 categories or values that need precise comparison (use bar-chart); a share of one whole (use waffle-chart); values that would need more than about 60 icons in a row (raise `unit`, or use bar-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/pictogram-chart
```

The file lands at `components/insightcharts/atoms/pictogram-chart.tsx`. `@insightcharts/pictogram-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { PictogramChart } from "insightcharts";

const data = [
  { city: "Tokyo", people: 37.1 },
  { city: "Delhi", people: 33.8 },
  { city: "Shanghai", people: 29.9 },
  { city: "São Paulo", people: 22.8 },
  { city: "Mexico City", people: 22.5 },
];

<PictogramChart
  data={data}
  name="city"
  value="people"
  unit={2}
  unitLabel="2 million people"
  format="{value}m"
  highlight="Delhi"
  title="Delhi had 33.8 million people in 2024, 3.3 million fewer than Tokyo"
  subtitle="Population of the five largest urban agglomerations, 2024"
  source="UN World Urbanization Prospects"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "pictogram-chart",
  "data": [
    { "city": "Tokyo", "people": 37.1 },
    { "city": "Delhi", "people": 33.8 },
    { "city": "Shanghai", "people": 29.9 },
    { "city": "São Paulo", "people": 22.8 },
    { "city": "Mexico City", "people": 22.5 }
  ],
  "name": "city",
  "value": "people",
  "unit": 2,
  "unitLabel": "2 million people",
  "format": "{value}m",
  "highlight": "Delhi",
  "title": "Delhi had 33.8 million people in 2024, 3.3 million fewer than Tokyo",
  "subtitle": "Population of the five largest urban agglomerations, 2024",
  "source": "UN World Urbanization Prospects",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Category field: one row of icons per category. |
| `value` (required) | `string` |  | Value field. |
| `unit` | `number` |  | Units per icon. Default: a round number giving the largest row about ten icons. |
| `unitLabel` | `string` |  | What one icon stands for, for the key line, e.g. "1 million people". |
| `icon` | `IconName \| "path://..."` | `"person"` | Built-in icon name from `core/icons.ts` ("person", "house", "car", "tree", "coin", "drop", "bolt", "wind-turbine", "wheat" and about 60 more) or a custom single SVG path. |
| `icons` | `Record<string, string>` |  | Icon per category key; falls back to `icon`. |
| `perRow` | `number` |  | Wrap rows after this many icons. Default: as many as fit. |
| `labels` | `boolean` | `true` | Print the value after each row. |
| `sort` | `"none" \| "asc" \| "desc"` | `"none"` | Row order. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [poster](https://insightcharts.dev/llms/poster.md)

### More examples

#### Houses, sorted

```tsx
import { PictogramChart } from "insightcharts";

const data = [
  { decade: "1970s", homes: 3.1 },
  { decade: "1980s", homes: 2.2 },
  { decade: "1990s", homes: 1.6 },
  { decade: "2000s", homes: 1.9 },
  { decade: "2010s", homes: 1.5 },
];

<PictogramChart
  data={data}
  name="decade"
  value="homes"
  unit={0.25}
  unitLabel="250,000 homes"
  icon="house"
  format="{value}m"
  title="The UK completed 3.1 million homes in the 1970s and 1.5 million in the 2010s"
  subtitle="New dwellings completed per decade, United Kingdom"
  source="ONS house building data"
  note="Rounded for illustration"
/>
```

#### Shares as drops

```tsx
import { PictogramChart } from "insightcharts";

const data = [
  { use: "Agriculture", litres: 70 },
  { use: "Industry", litres: 19 },
  { use: "Households", litres: 11 },
];

<PictogramChart
  data={data}
  name="use"
  value="litres"
  unit={5}
  unitLabel="5 of every 100 litres"
  icon="drop"
  format="{value}%"
  height={200}
  title="Agriculture accounts for 70% of global freshwater withdrawals"
  subtitle="Share of global freshwater withdrawals by sector"
  source="FAO AQUASTAT"
  note="Figures are approximate, for illustration"
/>
```

#### Stress: many icons wrap, long names

```tsx
import { PictogramChart } from "insightcharts";

const data = [
  { fleet: "Battery electric passenger cars", cars: 28.4 },
  { fleet: "Plug-in hybrids", cars: 12.1 },
  { fleet: "Hydrogen fuel cell", cars: 0.3 },
];

<PictogramChart
  data={data}
  name="fleet"
  value="cars"
  unit={0.5}
  unitLabel="500,000 cars"
  icon="car"
  format="{value}m"
  height={300}
  title="There were 28.4 million battery electric cars on the road in 2023"
  subtitle="Electric cars on the road worldwide, 2023"
  source="IEA Global EV Outlook 2024"
  note="Figures are approximate, for illustration"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/pictogram-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/pictogram-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Pill rank (`pill-rank`)

> Shows a ranked list as horizontally centred rounded bars, with each name in capitals on its pill, the value at the left edge and the rank at the right.

- Component: `PillRank` (import from `insightcharts`)
- Spec type: `"pill-rank"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A poster ranking of 4 to about 20 named things where the order and the overall silhouette matter more than fine differences: top cities, largest employers, league tables, with one row highlighted and optional reference rows set apart below.

### Avoid

Precise comparison of values (use bar-chart, where bars share a baseline); negative values (use diverging-bar-chart); change in rank over time (use bump-chart); more than about 25 rows (use data-table).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/pill-rank
```

The file lands at `components/insightcharts/atoms/pill-rank.tsx`. `@insightcharts/pill-rank-demo` adds a ready-made example next to it.

### Usage

```tsx
import { PillRank } from "insightcharts";

const data = [
  { river: "Nile", km: 6650 },
  { river: "Amazon", km: 6400 },
  { river: "Yangtze", km: 6300 },
  { river: "Mississippi-Missouri", km: 6275 },
  { river: "Yenisei", km: 5539 },
  { river: "Yellow River", km: 5464 },
  { river: "Ob-Irtysh", km: 5410 },
  { river: "Congo", km: 4700 },
  { river: "Danube", km: 2850 },
  { river: "Rhine", km: 1230 },
];

<PillRank
  data={data}
  name="river"
  value="km"
  format="{value} km"
  highlight="Congo"
  compare={["Danube", "Rhine"]}
  compareLabel="Europe, for comparison"
  title="The Congo is 4,700 km long"
  subtitle="Length of eight major river systems and two European rivers, kilometres"
  source="Encyclopaedia Britannica"
  note="Lengths of river systems are approximate and vary by source"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "pill-rank",
  "data": [
    { "river": "Nile", "km": 6650 },
    { "river": "Amazon", "km": 6400 },
    { "river": "Yangtze", "km": 6300 },
    { "river": "Mississippi-Missouri", "km": 6275 },
    { "river": "Yenisei", "km": 5539 },
    { "river": "Yellow River", "km": 5464 },
    { "river": "Ob-Irtysh", "km": 5410 },
    { "river": "Congo", "km": 4700 },
    { "river": "Danube", "km": 2850 },
    { "river": "Rhine", "km": 1230 }
  ],
  "name": "river",
  "value": "km",
  "format": "{value} km",
  "highlight": "Congo",
  "compare": ["Danube", "Rhine"],
  "compareLabel": "Europe, for comparison",
  "title": "The Congo is 4,700 km long",
  "subtitle": "Length of eight major river systems and two European rivers, kilometres",
  "source": "Encyclopaedia Britannica",
  "note": "Lengths of river systems are approximate and vary by source"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Name field: one row per data row. |
| `value` (required) | `string` |  | Value field: pill width. Non-positive values are dropped. |
| `sort` | `boolean` | `true` | Sort rows largest first. Set false to keep the data order. |
| `compare` | `string[]` |  | Names of rows that are not ranked: drawn below a dotted rule, without a rank number. |
| `compareLabel` | `string` |  | Short heading over the comparison rows, e.g. "For comparison". |
| `max` | `number` |  | Value that fills the full pill width. Default: the largest value. |
| `ranks` | `boolean` | `true` | Show the rank number at the right edge. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md), [network-poster](https://insightcharts.dev/llms/network-poster.md), [radial-poster](https://insightcharts.dev/llms/radial-poster.md), [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md)

### More examples

#### No highlight, click to select

```tsx
import { PillRank } from "insightcharts";

const data = [
  { hobby: "Reading", pct: 71 },
  { hobby: "Walking", pct: 64 },
  { hobby: "Cooking", pct: 58 },
  { hobby: "Gardening", pct: 41 },
  { hobby: "Cycling", pct: 33 },
  { hobby: "Swimming", pct: 27 },
  { hobby: "Knitting", pct: 12 },
];

<PillRank
  data={data}
  name="hobby"
  value="pct"
  format="{value}%"
  select
  title="71% of adults surveyed read for pleasure"
  subtitle="Share of 1,200 adults who did each activity in the past month"
  note="Illustrative survey figures"
/>
```

#### Stress: 16 rows, long names, values from 3 to 2,140

```tsx
import { PillRank } from "insightcharts";

const data = [
  { port: "Port of Saint-Hilaire-du-Rosier", teu: 2140 },
  { port: "Kessel Deepwater", teu: 1730 },
  { port: "Marrow Bay", teu: 1205 },
  { port: "New Alderney Container Terminal", teu: 980 },
  { port: "Tolland", teu: 760 },
  { port: "Vasque", teu: 512 },
  { port: "Great Northern Free Harbour and Dry Dock", teu: 430 },
  { port: "Orm", teu: 298 },
  // ... 8 more rows
];

<PillRank
  data={data}
  name="port"
  value="teu"
  format="compact"
  highlight="Tolland"
  title="Tolland handled 760 thousand containers in 2024"
  subtitle="Container throughput of 16 ports, thousand TEU, 2024"
  note="Illustrative figures for invented ports"
/>
```

#### Data order, no ranks

```tsx
import { PillRank } from "insightcharts";

const data = [
  { day: "Monday", visits: 312 },
  { day: "Tuesday", visits: 344 },
  { day: "Wednesday", visits: 371 },
  { day: "Thursday", visits: 366 },
  { day: "Friday", visits: 428 },
  { day: "Saturday", visits: 502 },
  { day: "Sunday", visits: 287 },
];

<PillRank
  data={data}
  name="day"
  value="visits"
  sort={false}
  ranks={false}
  highlight="Saturday"
  title="The library had 502 visits on Saturday"
  subtitle="Visits per day, one week in March"
  note="Illustrative figures"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/pill-rank.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/pill-rank.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Progress meter (`progress-meter`)

> A labelled horizontal meter of one value against a maximum or target, with the target marked and the value printed.

- Component: `ProgressMeter` (import from `insightcharts`)
- Spec type: `"progress-meter"`
- Level: atom. Category: figure.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Progress toward a goal, a quota or a capacity: funds raised, budget spent, share of a target reached. Stack several with `size: "sm"` to compare progress across a few items.

### Avoid

Comparing more than a handful of items (use `bar-chart`), anything without a meaningful end point (use `big-number`), or a gauge dial.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/progress-meter
```

The file lands at `components/insightcharts/atoms/progress-meter.tsx`. `@insightcharts/progress-meter-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ProgressMeter } from "insightcharts";

<ProgressMeter
  label="Homes with a heat pump or district heating"
  value={0.46}
  max={1}
  showMax={false}
  target={0.7}
  targetLabel="2030 target"
  context="Up from 31% in 2020. At the current rate the target is reached in 2033."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "progress-meter",
  "label": "Homes with a heat pump or district heating",
  "value": 0.46,
  "max": 1,
  "showMax": false,
  "target": 0.7,
  "targetLabel": "2030 target",
  "context": "Up from 31% in 2020. At the current rate the target is reached in 2033."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `number` |  | The current value. |
| `label` (required) | `string` |  | What is measured, sentence case. |
| `max` | `number` |  | End of the track. Defaults to the target, or 1 with no target. |
| `min` | `number` | `0` | Start of the track. |
| `target` | `number` |  | A goal or threshold, drawn as a tick and labelled. |
| `targetLabel` | `string` | `"Target"` | Name for the target tick. |
| `showMax` | `boolean` |  | Print "of {max}" after the value. Default: only when `max` is given. |
| `context` | `string` |  | A line under the meter that gives the number meaning. |
| `format` | `FormatSpec` |  | Number format. Defaults to `"percent"` when the track ends at 1 or less, otherwise `"auto"`. |
| `tone` | `"accent" \| "positive" \| "negative" \| "neutral"` | `"accent"` | Fill colour by meaning. |
| `size` | `"sm" \| "md"` | `"md"` | `sm` for dense stacks. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [report-page](https://insightcharts.dev/llms/report-page.md)

### More examples

#### Against a maximum

```tsx
import { ProgressMeter } from "insightcharts";

<ProgressMeter
  label="Annual carbon budget used"
  value={318}
  max={400}
  format="{value} Mt"
  tone="negative"
  context="With ten weeks of the year left."
/>
```

#### Target passed

```tsx
import { ProgressMeter } from "insightcharts";

<ProgressMeter
  label="Fundraising round"
  value={2340000}
  target={2000000}
  format="currency:USD"
  tone="positive"
  context="Closed 17% above the goal."
/>
```

#### Small, low value

```tsx
import { ProgressMeter } from "insightcharts";

<ProgressMeter
  size="sm"
  label="Rural fibre coverage"
  value={0.08}
  target={0.95}
  targetLabel="Goal"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/progress-meter.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/progress-meter.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Proportional area (`proportional-area`)

> Compares two to eight values as squares or circles whose areas are proportional to the values, each printed with its name and number.

- Component: `ProportionalArea` (import from `insightcharts`)
- Spec type: `"proportional-area"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A few quantities that differ a lot (2 times to 100 times), where the reader should feel the difference in size: lake areas, budgets, market sizes. Nest them to show one quantity inside another.

### Avoid

Values within about 30% of each other, where areas look the same (use block-bar or bar-chart); more than 8 values (use treemap or bar-chart); parts of one whole (use treemap or waffle-chart); negative values.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/proportional-area
```

The file lands at `components/insightcharts/atoms/proportional-area.tsx`. `@insightcharts/proportional-area-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ProportionalArea } from "insightcharts";

const data = [
  { lake: "Superior", area: 82100 },
  { lake: "Victoria", area: 68900 },
  { lake: "Tanganyika", area: 32900 },
  { lake: "Erie", area: 25700 },
  { lake: "Titicaca", area: 8370 },
];

<ProportionalArea
  data={data}
  name="lake"
  value="area"
  format="integer"
  ratio
  title="Lake Superior covers 82,100 km², 9.8 times Lake Titicaca"
  subtitle="Surface area of five lakes, square kilometres"
  source="Approximate published figures"
  note="Rounded, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "proportional-area",
  "data": [
    { "lake": "Superior", "area": 82100 },
    { "lake": "Victoria", "area": 68900 },
    { "lake": "Tanganyika", "area": 32900 },
    { "lake": "Erie", "area": 25700 },
    { "lake": "Titicaca", "area": 8370 }
  ],
  "name": "lake",
  "value": "area",
  "format": "integer",
  "ratio": true,
  "title": "Lake Superior covers 82,100 km², 9.8 times Lake Titicaca",
  "subtitle": "Surface area of five lakes, square kilometres",
  "source": "Approximate published figures",
  "note": "Rounded, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Category field: one shape per row. |
| `value` (required) | `string` |  | Value field. Each shape's area is proportional to it. |
| `shape` | `"square" \| "circle"` | `"square"` | Squares or circles. |
| `layout` | `"row" \| "nested" \| "packed"` | `"row"` | `row`: side by side on a common baseline. `nested`: inside one another from a shared corner (squares) or lowest point (circles). `packed`: clustered together. |
| `ratio` | `boolean \| string` |  | Print how many times the largest value is the smallest. `true` for "{largest} is {ratio} times {smallest}", or a template with those placeholders. |
| `sort` | `"none" \| "asc" \| "desc"` | `"none"` | Order of the shapes in the row layout. Nested and packed always draw largest first. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md), [count-poster](https://insightcharts.dev/llms/count-poster.md)

### More examples

#### Nested squares, highlight, click to select

```tsx
import { ProportionalArea } from "insightcharts";

const data = [
  { market: "All groceries", sales: 412 },
  { market: "Fresh produce", sales: 96 },
  { market: "Organic produce", sales: 21 },
  { market: "Organic berries", sales: 3.4 },
];

<ProportionalArea
  data={data}
  name="market"
  value="sales"
  layout="nested"
  format="£{value}m"
  highlight="Organic produce"
  select
  ratio="{largest} is {ratio} times {smallest}"
  title="Organic produce took £21m of £412m grocery sales in 2025"
  subtitle="Annual sales of one regional grocer by category, £ million, 2025"
  source="Illustrative data"
  note="Invented figures"
/>
```

#### Circles in a row

```tsx
import { ProportionalArea } from "insightcharts";

const data = [
  { reactor: "Harlow A", output: 1650 },
  { reactor: "Brant Point", output: 1100 },
  { reactor: "Selby 2", output: 470 },
  { reactor: "Test unit", output: 40 },
];

<ProportionalArea
  data={data}
  name="reactor"
  value="output"
  shape="circle"
  format="{value} MW"
  ratio
  title="Harlow A has a capacity of 1,650 MW"
  subtitle="Generating capacity of four power stations, megawatts"
  source="Illustrative data"
  note="Invented figures"
/>
```

#### Nested circles

```tsx
import { ProportionalArea } from "insightcharts";

const data = [
  { body: "Whole catchment", area: 5200 },
  { body: "Farmland", area: 2900 },
  { body: "Woodland", area: 1150 },
  { body: "Open water", area: 160 },
];

<ProportionalArea
  data={data}
  name="body"
  value="area"
  shape="circle"
  layout="nested"
  format="{value} km²"
  title="Farmland covers 2,900 km² of the 5,200 km² catchment"
  subtitle="Land cover of the River Teme catchment, square kilometres"
  source="Illustrative data"
  note="Invented figures"
/>
```

#### Stress: eight packed circles, very uneven, long names

```tsx
import { ProportionalArea } from "insightcharts";

const data = [
  { fund: "State pension and retirement benefits", spend: 124 },
  { fund: "Health services", spend: 88 },
  { fund: "Schools", spend: 52 },
  { fund: "Defence", spend: 31 },
  { fund: "Transport infrastructure", spend: 18 },
  { fund: "Courts and prisons", spend: 7.5 },
  { fund: "Overseas aid", spend: 2.2 },
  { fund: "National parks and heritage sites", spend: 0.6 },
];

<ProportionalArea
  data={data}
  name="fund"
  value="spend"
  shape="circle"
  layout="packed"
  format="{value}bn"
  ratio
  title="Pensions took 124bn of the 323.3bn budget"
  subtitle="Planned public spending by area, billions, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional country"
/>
```

#### Packed squares

```tsx
import { ProportionalArea } from "insightcharts";

const data = [
  { fund: "Pensions", spend: 124 },
  { fund: "Health", spend: 88 },
  { fund: "Schools", spend: 52 },
  { fund: "Defence", spend: 31 },
  { fund: "Transport", spend: 18 },
  { fund: "Courts", spend: 7.5 },
];

<ProportionalArea
  data={data}
  name="fund"
  value="spend"
  layout="packed"
  format="{value}bn"
  title="Health took 88bn of planned spending in 2025"
  subtitle="Planned public spending by area, billions, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional country"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/proportional-area.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/proportional-area.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Prose (`prose`)

> A readable block of narration at a 45-75 character measure, for the text between charts.

- Component: `Prose` (import from `insightcharts`)
- Spec type: `"prose"`
- Level: atom. Category: text.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

To say what a chart showed and introduce the next one. Use two or three short paragraphs at a time.

### Avoid

A single statement of fact (use `callout`), a quotation (use `pull-quote`), or sourcing and method notes (use `source-note`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/prose
```

The file lands at `components/insightcharts/atoms/prose.tsx`. `@insightcharts/prose-demo` adds a ready-made example next to it.

### Usage

```tsx
import { Prose } from "insightcharts";

<Prose
  text={"In 2015 solar supplied **3% of Europe's electricity**. Hydro supplied more than three times as much.\n\nPanel prices fell by about 80% in the years that followed. In 2024 solar generated more electricity than coal across the EU, according to [Ember's annual review](https://ember-energy.org).\n\nSolar's share differs by country. The next chart shows it for each EU member state."}
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "prose",
  "text": "In 2015 solar supplied **3% of Europe's electricity**. Hydro supplied more than three times as much.\n\nPanel prices fell by about 80% in the years that followed. In 2024 solar generated more electricity than coal across the EU, according to [Ember's annual review](https://ember-energy.org).\n\nSolar's share differs by country. The next chart shows it for each EU member state."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `text` | `string \| string[]` |  | Narration. Blank lines separate paragraphs. Supports `**bold**`, `*italic*` and `[link](url)`. |
| `children` | `ReactNode` |  | JSX alternative to `text`. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Body size: 14, 16 or 18px. |
| `measure` | `number` | `65` | Line length in characters, clamped to 45-75. |
| `lead` | `boolean` | `false` | Set the first paragraph a step larger. |
| `tone` | `"default" \| "muted"` | `"default"` | `muted` for secondary narration. |
| `align` | `"left" \| "center"` | `"left"` | Centres the block (text stays left-aligned). |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [annotated-timeline](https://insightcharts.dev/llms/annotated-timeline.md), [scrolly-chart](https://insightcharts.dev/llms/scrolly-chart.md), [section](https://insightcharts.dev/llms/section.md), [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md), [executive-brief](https://insightcharts.dev/llms/executive-brief.md), [explainer](https://insightcharts.dev/llms/explainer.md), [report-page](https://insightcharts.dev/llms/report-page.md), [scorecard](https://insightcharts.dev/llms/scorecard.md), [story-deck](https://insightcharts.dev/llms/story-deck.md), [timeline-story](https://insightcharts.dev/llms/timeline-story.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Lead paragraph, large

```tsx
import { Prose } from "insightcharts";

<Prose
  size="lg"
  lead
  text={[
    "The typical household energy bill almost doubled between the winter of 2020 and the winter of 2022.",
    "Wholesale prices have fallen since then. Standing charges and network costs have not fallen. The average bill is still about a third higher than it was in 2020.",
  ]}
/>
```

#### Muted aside, narrow measure

```tsx
import { Prose } from "insightcharts";

<Prose
  size="sm"
  tone="muted"
  measure={48}
  text="*How to read this section.* Each dot is one local authority. Dots further right have more installed capacity per person. The vertical position shows median household income."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/prose.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/prose.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Pull quote (`pull-quote`)

> A large quotation with its attribution.

- Component: `PullQuote` (import from `insightcharts`)
- Spec type: `"pull-quote"`
- Level: atom. Category: text.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

To quote a person on a finding the charts have already shown, or to break up a long run of charts. One per section at most.

### Avoid

Restating a number (use `big-number`) or the main fact of a chart (use `callout`). Never quote without attribution.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/pull-quote
```

The file lands at `components/insightcharts/atoms/pull-quote.tsx`. `@insightcharts/pull-quote-demo` adds a ready-made example next to it.

### Usage

```tsx
import { PullQuote } from "insightcharts";

<PullQuote
  quote="Solar set the midday wholesale price on most days in 2023. Our plans had assumed that would happen in the 2030s."
  attribution="Marit de Vries"
  role="Head of system operations, Dutch grid operator"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "pull-quote",
  "quote": "Solar set the midday wholesale price on most days in 2023. Our plans had assumed that would happen in the 2030s.",
  "attribution": "Marit de Vries",
  "role": "Head of system operations, Dutch grid operator"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `quote` | `string` |  | The words quoted, without quotation marks. |
| `children` | `ReactNode` |  | JSX alternative to `quote`. |
| `attribution` | `string` |  | Who said it. |
| `role` | `string` |  | Their role, or where it was said. |
| `cite` | `string` |  | Source URL: set as the blockquote `cite` and linked from the attribution. |
| `size` | `"md" \| "lg"` | `"lg"` | `lg` anchors a section; `md` sits inside a column. |
| `align` | `"left" \| "center"` | `"left"` | Left-aligned quotes carry a side rule; centred ones do not. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [quote-figure](https://insightcharts.dev/llms/quote-figure.md), [story-deck](https://insightcharts.dev/llms/story-deck.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Centered

```tsx
import { PullQuote } from "insightcharts";

<PullQuote
  align="center"
  quote="Rooftop solar is now the cheapest source of new electricity in our market."
  attribution="Luis Ortega"
  role="Energy economist"
/>
```

#### Medium, with source link

```tsx
import { PullQuote } from "insightcharts";

<PullQuote
  size="md"
  quote="Solar underbid coal in the afternoon power auctions for three years. The coal plants that could not reduce their output quickly enough in those hours were closed because they no longer covered their costs."
  attribution="European Electricity Review 2025"
  cite="https://ember-energy.org"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/pull-quote.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/pull-quote.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Radial bar chart (`radial-bar-chart`)

> Draws bars around a circle for data that repeats in a cycle, such as hours of the day or months of the year.

- Component: `RadialBarChart` (import from `insightcharts`)
- Spec type: `"radial-bar-chart"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Only when the dimension is cyclical and the wrap-around matters: activity by hour of day, seasonality by month, wind by compass direction. The first category is placed at 12 o'clock.

### Avoid

Any dimension that does not wrap around: categories, rankings, years (use bar-chart); precise comparison of values, since bars further out look bigger (use bar-chart or line-chart); more than about 3 stacked series.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/radial-bar-chart
```

The file lands at `components/insightcharts/atoms/radial-bar-chart.tsx`. `@insightcharts/radial-bar-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { RadialBarChart } from "insightcharts";

const data = [
  { hour: "00:00", trips: 2.1 },
  { hour: "01:00", trips: 1.2 },
  { hour: "02:00", trips: 0.8 },
  { hour: "03:00", trips: 0.6 },
  { hour: "04:00", trips: 0.7 },
  { hour: "05:00", trips: 1.4 },
  { hour: "06:00", trips: 3.6 },
  { hour: "07:00", trips: 6.9 },
  { hour: "08:00", trips: 8.8 },
  { hour: "09:00", trips: 6.4 },
  { hour: "10:00", trips: 5.1 },
  { hour: "11:00", trips: 5.3 },
  { hour: "12:00", trips: 5.9 },
  { hour: "13:00", trips: 5.6 },
  { hour: "14:00", trips: 5.4 },
  { hour: "15:00", trips: 6 },
  { hour: "16:00", trips: 7.4 },
  { hour: "17:00", trips: 9.2 },
  { hour: "18:00", trips: 8.1 },
  { hour: "19:00", trips: 6 },
  { hour: "20:00", trips: 4.6 },
  { hour: "21:00", trips: 3.9 },
  { hour: "22:00", trips: 3.3 },
  { hour: "23:00", trips: 2.7 },
];

<RadialBarChart
  data={data}
  x="hour"
  y="trips"
  format="{value}%"
  centerLabel="24 hours"
  highlight={["08:00", "17:00"]}
  title="Weekday bike-share trips peak at 9.2% in the 5pm hour and 8.8% in the 8am hour"
  subtitle="Share of daily bike-share trips starting in each hour, weekdays"
  source="Illustrative bike-share data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "radial-bar-chart",
  "data": [
    { "hour": "00:00", "trips": 2.1 },
    { "hour": "01:00", "trips": 1.2 },
    { "hour": "02:00", "trips": 0.8 },
    { "hour": "03:00", "trips": 0.6 },
    { "hour": "04:00", "trips": 0.7 },
    { "hour": "05:00", "trips": 1.4 },
    { "hour": "06:00", "trips": 3.6 },
    { "hour": "07:00", "trips": 6.9 },
    { "hour": "08:00", "trips": 8.8 },
    { "hour": "09:00", "trips": 6.4 },
    { "hour": "10:00", "trips": 5.1 },
    { "hour": "11:00", "trips": 5.3 },
    { "hour": "12:00", "trips": 5.9 },
    { "hour": "13:00", "trips": 5.6 },
    { "hour": "14:00", "trips": 5.4 },
    { "hour": "15:00", "trips": 6 },
    { "hour": "16:00", "trips": 7.4 },
    { "hour": "17:00", "trips": 9.2 },
    { "hour": "18:00", "trips": 8.1 },
    { "hour": "19:00", "trips": 6 },
    { "hour": "20:00", "trips": 4.6 },
    { "hour": "21:00", "trips": 3.9 },
    { "hour": "22:00", "trips": 3.3 },
    { "hour": "23:00", "trips": 2.7 }
  ],
  "x": "hour",
  "y": "trips",
  "format": "{value}%",
  "centerLabel": "24 hours",
  "highlight": ["08:00", "17:00"],
  "title": "Weekday bike-share trips peak at 9.2% in the 5pm hour and 8.8% in the 8am hour",
  "subtitle": "Share of daily bike-share trips starting in each hour, weekdays",
  "source": "Illustrative bike-share data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | The cyclical category field, in cycle order. |
| `y` (required) | `string \| string[]` |  | Value field, or several to stack. |
| `series` | `string` |  | Field that splits rows into stacked series (long data). |
| `labelEvery` | `number` |  | Label every nth category around the rim. Default: chosen to avoid crowding. |
| `labels` | `boolean` |  | Print the value on the tallest bar. Default: on for a single series. |
| `centerFirst` | `boolean` | `false` | Centre the first category on 12 o'clock (compass directions) instead of starting its band there (hours). |
| `centerLabel` | `string` |  | Text in the centre of the ring, e.g. "24 hours". |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [story-deck](https://insightcharts.dev/llms/story-deck.md)

### More examples

#### Months

```tsx
import { RadialBarChart } from "insightcharts";

const data = [
  { month: "Jan", mm: 48 },
  { month: "Feb", mm: 41 },
  { month: "Mar", mm: 38 },
  { month: "Apr", mm: 52 },
  { month: "May", mm: 71 },
  { month: "Jun", mm: 96 },
  { month: "Jul", mm: 118 },
  { month: "Aug", mm: 112 },
  // ... 4 more rows
];

<RadialBarChart
  data={data}
  x="month"
  y="mm"
  format="{value} mm"
  centerLabel="Year"
  title="Munich averages 118 mm of rain in July and 38 mm in March"
  subtitle="Average monthly rainfall, Munich, 1991-2020"
  source="Deutscher Wetterdienst"
  note="Rounded, approximate figures for illustration"
/>
```

#### Stacked series

```tsx
import { RadialBarChart } from "insightcharts";

const data = [
  { hour: "0", weekday: 38, weekend: 18 },
  { hour: "1", weekday: 26, weekend: 18 },
  { hour: "2", weekday: 18, weekend: 18 },
  { hour: "3", weekday: 14, weekend: 18 },
  { hour: "4", weekday: 17, weekend: 19 },
  { hour: "5", weekday: 34, weekend: 20 },
  { hour: "6", weekday: 82, weekend: 22 },
  { hour: "7", weekday: 141, weekend: 26 },
  // ... 16 more rows
];

<RadialBarChart
  data={data}
  x="hour"
  y={["weekday", "weekend"]}
  names={{ weekday: "Weekdays", weekend: "Weekends" }}
  centerLabel="Hour of day"
  title="Weekday emergency calls peak at 172 per hour at 5pm"
  subtitle="Average emergency calls per hour by hour of day, weekdays and weekends"
  source="Illustrative data"
/>
```

#### Stress: long labels, compass

```tsx
import { RadialBarChart } from "insightcharts";

const data = [
  { direction: "North", share: 6 },
  { direction: "North-north-east", share: 4 },
  { direction: "North-east", share: 5 },
  { direction: "East-north-east", share: 3 },
  { direction: "East", share: 4 },
  { direction: "East-south-east", share: 3 },
  { direction: "South-east", share: 5 },
  { direction: "South-south-east", share: 6 },
  // ... 8 more rows
];

<RadialBarChart
  data={data}
  x="direction"
  y="share"
  format="{value}%"
  centerFirst
  height={420}
  title="The wind at Heathrow blows from the south-west 16% of the time"
  subtitle="Share of hours by wind direction, Heathrow, annual average"
  source="Illustrative data based on Met Office wind roses"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/radial-bar-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/radial-bar-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Radial spokes (`radial-spokes`)

> Draws one spoke per row radiating from a centre disc, each as long as its value, with the name and value set on an outer ring.

- Component: `RadialSpokes` (import from `insightcharts`)
- Spec type: `"radial-spokes"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A poster of 4 to 12 effects, causes or attributes of one subject, which sits in the centre as an icon or a short label: what a household's energy goes on, the side effects of one drug, the scores of one product.

### Avoid

Precise comparison or a ranking (use bar-chart or pill-rank); a dimension that is a cycle, such as hours or months (use radial-bar-chart); more than 12 rows (use bar-chart); several subjects compared on the same attributes (use small-multiples or heatmap).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/radial-spokes
```

The file lands at `components/insightcharts/atoms/radial-spokes.tsx`. `@insightcharts/radial-spokes-demo` adds a ready-made example next to it.

### Usage

```tsx
import { RadialSpokes } from "insightcharts";

const data = [
  { use: "Space heating", share: 42 },
  { use: "Hot water", share: 17 },
  { use: "Cooking", share: 6 },
  { use: "Fridge and freezer", share: 8 },
  { use: "Laundry", share: 7 },
  { use: "Lighting", share: 5 },
  { use: "Screens and computers", share: 9 },
  { use: "Everything else", share: 6 },
];

<RadialSpokes
  data={data}
  name="use"
  value="share"
  format="{value}%"
  icon="house"
  highlight="Space heating"
  title="Space heating uses 42% of a home's energy"
  subtitle="Share of household energy by end use, a typical home in a cool climate"
  note="Illustrative figures"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "radial-spokes",
  "data": [
    { "use": "Space heating", "share": 42 },
    { "use": "Hot water", "share": 17 },
    { "use": "Cooking", "share": 6 },
    { "use": "Fridge and freezer", "share": 8 },
    { "use": "Laundry", "share": 7 },
    { "use": "Lighting", "share": 5 },
    { "use": "Screens and computers", "share": 9 },
    { "use": "Everything else", "share": 6 }
  ],
  "name": "use",
  "value": "share",
  "format": "{value}%",
  "icon": "house",
  "highlight": "Space heating",
  "title": "Space heating uses 42% of a home's energy",
  "subtitle": "Share of household energy by end use, a typical home in a cool climate",
  "note": "Illustrative figures"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Name field: one spoke per row, in data order, clockwise. |
| `value` (required) | `string` |  | Value field: spoke length from the centre disc. |
| `shape` | `"bar" \| "line"` | `"bar"` | A thick tapered bar with a round head, or a thin line ending in a dot. |
| `icon` | `string` |  | Icon in the centre disc: a built-in name or `path://`. |
| `centerLabel` | `string` |  | Short text in the centre disc, used when there is no `icon`. |
| `ring` | `boolean` | `true` | Dotted outer ring at the scale maximum, where the labels sit. |
| `max` | `number` |  | Value that reaches the outer ring. Default: the largest value. |
| `startAngle` | `number` | `0` | Angle of the first spoke in degrees clockwise from 12 o'clock. |
| `sweep` | `number` | `360` | Arc the spokes are spread over, in degrees. 180 makes a fan. |
| `colorBy` | `"single" \| "value"` | `"single"` | The accent for every spoke, or a shade by value along the sequential ramp. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md), [radial-poster](https://insightcharts.dev/llms/radial-poster.md)

### More examples

#### Thin lines, centre label, click to select

```tsx
import { RadialSpokes } from "insightcharts";

const data = [
  { aspect: "Battery life", score: 8.6 },
  { aspect: "Camera", score: 7.1 },
  { aspect: "Screen", score: 9 },
  { aspect: "Speed", score: 6.4 },
  { aspect: "Build", score: 7.8 },
  { aspect: "Value", score: 5.2 },
];

<RadialSpokes
  data={data}
  name="aspect"
  value="score"
  shape="line"
  max={10}
  format={{ minimumFractionDigits: 1 }}
  centerLabel="Model K phone"
  select
  title="Reviewers scored the Model K's screen 9.0 out of 10"
  subtitle="Average review score by aspect, out of 10. The ring marks 10."
  note="Illustrative scores for an invented phone"
/>
```

#### Fan over 180 degrees, shaded by value

```tsx
import { RadialSpokes } from "insightcharts";

const data = [
  { effect: "Drowsiness", pct: 31 },
  { effect: "Dry mouth", pct: 22 },
  { effect: "Headache", pct: 14 },
  { effect: "Nausea", pct: 9 },
  { effect: "Dizziness", pct: 6 },
  { effect: "Rash", pct: 2 },
];

<RadialSpokes
  data={data}
  name="effect"
  value="pct"
  format="{value}%"
  sweep={180}
  colorBy="value"
  icon="drop"
  title="31% of trial patients reported drowsiness"
  subtitle="Share of 840 patients reporting each side effect in a 12-week trial"
  note="Illustrative figures for an invented medicine"
/>
```

#### Stress: 12 spokes, long labels, values from 0 to 96

```tsx
import { RadialSpokes } from "insightcharts";

const data = [
  { cost: "Unplanned maintenance and emergency call-outs", k: 96 },
  { cost: "Fuel", k: 71 },
  { cost: "Crew wages and overtime", k: 88 },
  { cost: "Port fees", k: 34 },
  { cost: "Insurance", k: 27 },
  { cost: "Training", k: 0 },
  { cost: "Catering", k: 12 },
  { cost: "Navigation and satellite communications", k: 19 },
  // ... 4 more rows
];

<RadialSpokes
  data={data}
  name="cost"
  value="k"
  format="£{value}k"
  centerLabel="One ferry"
  highlight={["Unplanned maintenance and emergency call-outs"]}
  height={560}
  title="Unplanned maintenance cost £96,000 per ferry in 2024"
  subtitle="Annual running cost of one ferry by item, £ thousand, 2024"
  note="Illustrative figures for an invented operator"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/radial-spokes.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/radial-spokes.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Ribbon chart (`ribbon-chart`)

> One filled band per entity across periods: its thickness is its value in each period and its vertical position is its rank, so bands cross as the order changes.

- Component: `RibbonChart` (import from `insightcharts`)
- Spec type: `"ribbon-chart"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

4 to 8 entities over 4 to 10 periods when both the size of each and the changing order matter, and the graphic should read as one flowing form: market shares, harvests, medal tables, budget lines.

### Avoid

Totals that matter more than order, or a smooth centred stream of many periods (use area-chart, which has stacked and stream modes); rank alone (use bump-chart); more than 8 entities or 10 periods (use line-chart or small-multiples); values that can be negative (use line-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/ribbon-chart
```

The file lands at `components/insightcharts/atoms/ribbon-chart.tsx`. `@insightcharts/ribbon-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { RibbonChart } from "insightcharts";

const data = [
  { year: "2019", Potatoes: 7.4, Carrots: 5.1, Onions: 4.2, Beans: 2.6, Squash: 1.2 },
  { year: "2020", Potatoes: 6.9, Carrots: 5.6, Onions: 3.8, Beans: 3.1, Squash: 2.3 },
  { year: "2021", Potatoes: 6.1, Carrots: 5.9, Onions: 3.1, Beans: 3.4, Squash: 3.9 },
  { year: "2022", Potatoes: 5.2, Carrots: 6.3, Onions: 2.9, Beans: 3.2, Squash: 5 },
  { year: "2023", Potatoes: 4.8, Carrots: 6, Onions: 2.4, Beans: 3.6, Squash: 6.1 },
  { year: "2024", Potatoes: 4.1, Carrots: 6.2, Onions: 2.2, Beans: 3.5, Squash: 6.8 },
];

<RibbonChart
  data={data}
  x="year"
  y={["Potatoes", "Carrots", "Onions", "Beans", "Squash"]}
  format="{value} t"
  title="The squash harvest rose from 1.2 to 6.8 tonnes between 2019 and 2024"
  subtitle="Harvest of five crops at one community farm, tonnes, 2019 to 2024, largest at the top each year"
  note="Illustrative figures."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "ribbon-chart",
  "data": [
    { "year": "2019", "Potatoes": 7.4, "Carrots": 5.1, "Onions": 4.2, "Beans": 2.6, "Squash": 1.2 },
    { "year": "2020", "Potatoes": 6.9, "Carrots": 5.6, "Onions": 3.8, "Beans": 3.1, "Squash": 2.3 },
    { "year": "2021", "Potatoes": 6.1, "Carrots": 5.9, "Onions": 3.1, "Beans": 3.4, "Squash": 3.9 },
    { "year": "2022", "Potatoes": 5.2, "Carrots": 6.3, "Onions": 2.9, "Beans": 3.2, "Squash": 5 },
    { "year": "2023", "Potatoes": 4.8, "Carrots": 6, "Onions": 2.4, "Beans": 3.6, "Squash": 6.1 },
    { "year": "2024", "Potatoes": 4.1, "Carrots": 6.2, "Onions": 2.2, "Beans": 3.5, "Squash": 6.8 }
  ],
  "x": "year",
  "y": ["Potatoes", "Carrots", "Onions", "Beans", "Squash"],
  "format": "{value} t",
  "title": "The squash harvest rose from 1.2 to 6.8 tonnes between 2019 and 2024",
  "subtitle": "Harvest of five crops at one community farm, tonnes, 2019 to 2024, largest at the top each year",
  "note": "Illustrative figures."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Period field: one column of the ribbon per distinct value, in data order. |
| `y` (required) | `string \| string[]` |  | Value field (long data), or one column per entity (wide data). Band thickness; negative values are drawn as zero. |
| `series` | `string` |  | Entity field, for long data. |
| `values` | `boolean` | `true` | Print each value inside its band at every period where it fits. |
| `labels` | `"both" \| "end"` |  | Entity names at both ends, or only at the end. Default: both, end only on narrow screens. |
| `names` | `Record<string, string>` |  | Display names for entity keys. |
| `colorBy` | `"auto" \| "series" \| "none"` | `"auto"` | `auto`: the largest entities take the theme's colours and any past the palette size (at most 8) are grey. `series`: every band gets its own colour, the extra ones derived from the theme's own. `none`: every band in the accent. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [timeline-poster](https://insightcharts.dev/llms/timeline-poster.md)

### More examples

#### Long data, one highlighted

```tsx
import { RibbonChart } from "insightcharts";

const data = [
  { method: "Cash", year: "2016", share: 46 },
  { method: "Cash", year: "2018", share: 38 },
  { method: "Cash", year: "2020", share: 27 },
  { method: "Cash", year: "2022", share: 19 },
  { method: "Cash", year: "2024", share: 12 },
  { method: "Debit card", year: "2016", share: 31 },
  { method: "Debit card", year: "2018", share: 34 },
  { method: "Debit card", year: "2020", share: 37 },
  // ... 17 more rows
];

<RibbonChart
  data={data}
  series="method"
  x="year"
  y="share"
  highlight="Phone or watch"
  format="{value}%"
  title="Phone and watch payments rose from 2% to 36% of till sales between 2016 and 2024"
  subtitle="Share of till transactions by payment method at one grocery chain, 2016 to 2024"
  note="Illustrative figures."
/>
```

#### Ten entities, one colour each

```tsx
import { RibbonChart } from "insightcharts";

const data = [
  { tea: "Assam", year: "2020", sold: 40 },
  { tea: "Assam", year: "2021", sold: 38 },
  { tea: "Assam", year: "2022", sold: 36 },
  { tea: "Assam", year: "2023", sold: 33 },
  { tea: "Assam", year: "2024", sold: 30 },
  { tea: "Earl Grey", year: "2020", sold: 34 },
  { tea: "Earl Grey", year: "2021", sold: 35 },
  { tea: "Earl Grey", year: "2022", sold: 33 },
  // ... 42 more rows
];

<RibbonChart
  data={data}
  series="tea"
  x="year"
  y="sold"
  colorBy="series"
  format="{value} kg"
  title="Sencha sales rose from 12 kg to 41 kg between 2020 and 2024"
  subtitle="Loose tea sold per year by one shop, ten teas, kilograms, 2020 to 2024, largest at the top each year"
  note="Illustrative figures."
/>
```

#### Stress: 7 entities, 8 periods, thin bands

```tsx
import { RibbonChart } from "insightcharts";

const data = [
  { club: "Rowing club", season: "2017", medals: 14 },
  { club: "Rowing club", season: "2018", medals: 12 },
  { club: "Rowing club", season: "2019", medals: 15 },
  { club: "Rowing club", season: "2020", medals: 11 },
  { club: "Rowing club", season: "2021", medals: 9 },
  { club: "Rowing club", season: "2022", medals: 8 },
  { club: "Rowing club", season: "2023", medals: 7 },
  { club: "Rowing club", season: "2024", medals: 6 },
  // ... 48 more rows
];

<RibbonChart
  data={data}
  series="club"
  x="season"
  y="medals"
  title="The athletics club's medals rose from 9 in 2017 to 21 in 2024"
  subtitle="Medals won per season by seven clubs in one regional league, 2017 to 2024"
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/ribbon-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/ribbon-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Sankey chart (`sankey-chart`)

> Shows how a quantity flows from sources through stages to destinations, with link width proportional to the flow.

- Component: `SankeyChart` (import from `insightcharts`)
- Spec type: `"sankey-chart"`
- Level: atom. Category: flow.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Where things come from and where they go: energy from fuel to end use, budget from revenue to spending, users from channel to outcome. Works best with 2 to 4 stages and up to about 20 nodes.

### Avoid

A single sequence of steps with drop-off (use funnel-chart); comparing a few totals (use bar-chart); flows that loop back (cycles cannot be drawn and are dropped); more than about 40 links.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/sankey-chart
```

The file lands at `components/insightcharts/atoms/sankey-chart.tsx`. `@insightcharts/sankey-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { SankeyChart } from "insightcharts";

const data = [
  { from: "Coal", to: "Electricity", twh: 290 },
  { from: "Gas", to: "Electricity", twh: 210 },
  { from: "Gas", to: "Heat", twh: 330 },
  { from: "Wind and solar", to: "Electricity", twh: 240 },
  { from: "Nuclear", to: "Electricity", twh: 120 },
  { from: "Oil", to: "Transport", twh: 560 },
  { from: "Oil", to: "Heat", twh: 90 },
  { from: "Electricity", to: "Homes", twh: 280 },
  { from: "Electricity", to: "Industry", twh: 330 },
  { from: "Electricity", to: "Transport", twh: 30 },
  { from: "Electricity", to: "Losses", twh: 220 },
  { from: "Heat", to: "Homes", twh: 270 },
  { from: "Heat", to: "Industry", twh: 150 },
];

<SankeyChart
  data={data}
  from="from"
  to="to"
  value="twh"
  format="{value} TWh"
  title="220 TWh of the 860 TWh used to generate electricity was lost"
  subtitle="Energy flows from fuel to end use, terawatt-hours per year"
  source="Illustrative national energy balance"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "sankey-chart",
  "data": [
    { "from": "Coal", "to": "Electricity", "twh": 290 },
    { "from": "Gas", "to": "Electricity", "twh": 210 },
    { "from": "Gas", "to": "Heat", "twh": 330 },
    { "from": "Wind and solar", "to": "Electricity", "twh": 240 },
    { "from": "Nuclear", "to": "Electricity", "twh": 120 },
    { "from": "Oil", "to": "Transport", "twh": 560 },
    { "from": "Oil", "to": "Heat", "twh": 90 },
    { "from": "Electricity", "to": "Homes", "twh": 280 },
    { "from": "Electricity", "to": "Industry", "twh": 330 },
    { "from": "Electricity", "to": "Transport", "twh": 30 },
    { "from": "Electricity", "to": "Losses", "twh": 220 },
    { "from": "Heat", "to": "Homes", "twh": 270 },
    { "from": "Heat", "to": "Industry", "twh": 150 }
  ],
  "from": "from",
  "to": "to",
  "value": "twh",
  "format": "{value} TWh",
  "title": "220 TWh of the 860 TWh used to generate electricity was lost",
  "subtitle": "Energy flows from fuel to end use, terawatt-hours per year",
  "source": "Illustrative national energy balance"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `from` | `string` | `"source"` | Field naming where each flow starts. Not called `source` because that is the figure's source line. |
| `to` | `string` | `"target"` | Field naming where each flow ends. |
| `value` | `string` | `"value"` | Flow size field. Non-positive flows are dropped. |
| `orientation` | `"auto" \| "horizontal" \| "vertical"` | `"auto"` | Left to right, or top to bottom for narrow columns with short names. |
| `labels` | `boolean` | `true` | Print each node's total after its name. |
| `names` | `Record<string, string>` |  | Display names for node keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Two stages, highlight

```tsx
import { SankeyChart } from "insightcharts";

const data = [
  { channel: "Organic search", outcome: "Signed up", users: 4200 },
  { channel: "Organic search", outcome: "Left", users: 9800 },
  { channel: "Paid ads", outcome: "Signed up", users: 1500 },
  { channel: "Paid ads", outcome: "Left", users: 10500 },
  { channel: "Referral", outcome: "Signed up", users: 2600 },
  { channel: "Referral", outcome: "Left", users: 2400 },
];

<SankeyChart
  data={data}
  from="channel"
  to="outcome"
  value="users"
  highlight="Referral"
  height={300}
  title="52% of referred visitors signed up last quarter"
  subtitle="Visitors by acquisition channel and outcome, last quarter"
  note="Illustrative data"
/>
```

#### Vertical

```tsx
import { SankeyChart } from "insightcharts";

const data = [
  { from: "Taxes", to: "Budget", bn: 820 },
  { from: "Borrowing", to: "Budget", bn: 130 },
  { from: "Other", to: "Budget", bn: 90 },
  { from: "Budget", to: "Health", bn: 250 },
  { from: "Budget", to: "Welfare", bn: 310 },
  { from: "Budget", to: "Schools", bn: 120 },
  { from: "Budget", to: "Defence", bn: 60 },
  { from: "Budget", to: "Interest", bn: 110 },
  // ... 1 more rows
];

<SankeyChart
  data={data}
  from="from"
  to="to"
  value="bn"
  format="£{value}bn"
  orientation="vertical"
  title="Borrowing funded £130bn of the £1,040bn budget"
  subtitle="Government revenue by source and spending by area, £ billion"
  note="Illustrative data"
/>
```

#### Stress: four stages, many nodes, long names, a loop

```tsx
import { SankeyChart } from "insightcharts";

const data = [
  { from: "Domestic crude oil production", to: "Refineries", pj: 410 },
  { from: "Imported crude oil", to: "Refineries", pj: 620 },
  { from: "Natural gas fields", to: "Gas processing plants", pj: 540 },
  { from: "Imported liquefied natural gas", to: "Gas processing plants", pj: 180 },
  { from: "Coal mines", to: "Power stations", pj: 260 },
  { from: "Wind farms", to: "Power stations", pj: 150 },
  { from: "Solar parks", to: "Power stations", pj: 90 },
  { from: "Hydroelectric dams", to: "Power stations", pj: 70 },
  // ... 16 more rows
];

<SankeyChart
  data={data}
  from="from"
  to="to"
  value="pj"
  format="{value} PJ"
  height={520}
  title="Power stations lost 400 PJ of the 1,060 PJ they took in"
  subtitle="National energy balance from primary supply to final use, petajoules"
  note="Illustrative data. One circular flow in the data is left out"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/sankey-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/sankey-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Scale ladder (`scale-ladder`)

> A tall vertical band graded along one scale (linear or log, running up or down) with each item placed at its true position and labelled with an icon, its name and its value on alternating sides.

- Component: `ScaleLadder` (import from `insightcharts`)
- Spec type: `"scale-ladder"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Answering how deep, how high, how hot, how old or how far each of 4 to about 20 things is on one shared scale, when the reader needs the positions themselves: depths, altitudes, temperatures, ages, distances. Use `zones` to name ranges along the scale.

### Avoid

Comparing sizes rather than positions (use bar-chart or lollipop-chart); events with start and end dates (use timeline-chart); a distribution of many unnamed values (use strip-plot or histogram).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/scale-ladder
```

The file lands at `components/insightcharts/atoms/scale-ladder.tsx`. `@insightcharts/scale-ladder-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ScaleLadder } from "insightcharts";

const data = [
  { thing: "Fridge", c: 4 },
  { thing: "Chocolate melts", c: 34 },
  { thing: "Egg white sets", c: 62 },
  { thing: "Water boils", c: 100, icon: "drop" },
  { thing: "Sugar caramelises", c: 170 },
  { thing: "Deep-frying oil", c: 180, icon: "drop" },
  { thing: "Bread bakes", c: 220 },
  { thing: "Home oven at full heat", c: 250 },
  { thing: "Wood-fired pizza oven", c: 450 },
];

<ScaleLadder
  data={data}
  name="thing"
  value="c"
  iconField="icon"
  format="{value}°C"
  scaleLabel="Temperature"
  min={0}
  max={500}
  zones={[
    { from: 0, to: 100, label: "Below boiling" },
    { from: 100, to: 250, label: "Home oven range" },
    { from: 250, to: 500, label: "Wood-fired oven range" },
  ]}
  title="Nine kitchen temperatures from 4°C to 450°C"
  subtitle="Typical temperatures in a kitchen, degrees Celsius"
  note="Approximate, rounded figures."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "scale-ladder",
  "data": [
    { "thing": "Fridge", "c": 4 },
    { "thing": "Chocolate melts", "c": 34 },
    { "thing": "Egg white sets", "c": 62 },
    { "thing": "Water boils", "c": 100, "icon": "drop" },
    { "thing": "Sugar caramelises", "c": 170 },
    { "thing": "Deep-frying oil", "c": 180, "icon": "drop" },
    { "thing": "Bread bakes", "c": 220 },
    { "thing": "Home oven at full heat", "c": 250 },
    { "thing": "Wood-fired pizza oven", "c": 450 }
  ],
  "name": "thing",
  "value": "c",
  "iconField": "icon",
  "format": "{value}°C",
  "scaleLabel": "Temperature",
  "min": 0,
  "max": 500,
  "zones": [
    { "from": 0, "to": 100, "label": "Below boiling" },
    { "from": 100, "to": 250, "label": "Home oven range" },
    { "from": 250, "to": 500, "label": "Wood-fired oven range" }
  ],
  "title": "Nine kitchen temperatures from 4°C to 450°C",
  "subtitle": "Typical temperatures in a kitchen, degrees Celsius",
  "note": "Approximate, rounded figures."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Field holding each item's name. |
| `value` (required) | `string` |  | Field holding each item's position on the scale. |
| `icon` | `IconInput` |  | One icon for every item: a built-in name or a `path://` string. Items without an icon get a dot. |
| `iconField` | `string` |  | Field holding a per-item icon name or `path://` string. Overrides `icon`. |
| `scale` | `"linear" \| "log"` | `"linear"` | Log spaces the scale by powers of ten; the heading over the band says so. |
| `direction` | `"up" \| "down"` | `"up"` | `up`: larger values higher (height, temperature). `down`: larger values lower (depth, age). |
| `min` | `number` |  | Start of the scale. Default: a round number at or below the smallest value. |
| `max` | `number` |  | End of the scale. Default: a round number at or above the largest value. |
| `ticks` | `number[]` |  | Values that get a boxed label on the band. Default: round steps, or powers of ten on a log scale. |
| `zones` | `{ from: number; to: number; label: string }[]` |  | Named ranges along the scale, shaded across the graphic and named along its outer edge. |
| `scaleLabel` | `string` |  | Heading over the band: the measure and its unit, e.g. "Depth, metres". |
| `names` | `Record<string, string>` |  | Display names for item keys. |
| `bandWidth` | `number` |  | Width of the band in px, at most 40% of the plot width. Default 60, or 46 on narrow screens. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [profile-poster](https://insightcharts.dev/llms/profile-poster.md), [scale-poster](https://insightcharts.dev/llms/scale-poster.md)

### More examples

#### Depth, log scale, running down, one highlighted

```tsx
import { ScaleLadder } from "insightcharts";

const data = [
  { thing: "Water main", m: 1.2, icon: "drop" },
  { thing: "Street tree roots", m: 2, icon: "tree" },
  { thing: "Cellar floor", m: 3, icon: "house" },
  { thing: "Main sewer", m: 6 },
  { thing: "Metro platform", m: 24, icon: "person" },
  { thing: "Road tunnel", m: 40, icon: "car" },
  { thing: "Geothermal borehole", m: 180, icon: "bolt" },
  { thing: "Drinking-water well", m: 320, icon: "drop" },
];

<ScaleLadder
  data={data}
  name="thing"
  value="m"
  iconField="icon"
  scale="log"
  direction="down"
  scaleLabel="Depth below street level, metres"
  format="{value} m"
  highlight="Drinking-water well"
  title="The drinking-water well reached 320 metres below street level"
  subtitle="Depth of eight things under one city street, metres below street level"
  note="Illustrative figures for an invented city."
/>
```

#### Stress: 14 items, crowded values, long names

```tsx
import { ScaleLadder } from "insightcharts";

const data = [
  { structure: "Cathedral spire", m: 96 },
  { structure: "Old telecommunications tower", m: 142 },
  { structure: "Harbour crane", m: 68 },
  { structure: "Riverside residential tower, phase two", m: 131 },
  { structure: "City hall clock tower", m: 74 },
  { structure: "Northgate office block", m: 88 },
  { structure: "Stadium floodlight mast", m: 62 },
  { structure: "University library", m: 41 },
  // ... 6 more rows
];

<ScaleLadder
  data={data}
  name="structure"
  value="m"
  icon="square"
  scaleLabel="Height, metres"
  format="{value} m"
  min={0}
  title="The port wind turbine reached 198 metres at its blade tip"
  subtitle="Height of 14 structures in one city, metres above ground"
  note="Illustrative figures for an invented city."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/scale-ladder.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/scale-ladder.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Scatter chart (`scatter-chart`)

> Plots two numeric measures against each other, one dot per row, with optional bubble size, group colour, selective labels and a trend line.

- Component: `ScatterChart` (import from `insightcharts`)
- Spec type: `"scatter-chart"`
- Level: atom. Category: relationship.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Showing whether and how two measures move together, spotting clusters and outliers, and placing named entities in a two-dimensional space (with quadrant lines via `annotations`).

### Avoid

A measure over time (use line-chart); one numeric measure by category (use beeswarm-chart or strip-plot); fewer than about 8 points (use bar-chart or a table); more than 4 colour groups (facet with small-multiples).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/scatter-chart
```

The file lands at `components/insightcharts/atoms/scatter-chart.tsx`. `@insightcharts/scatter-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ScatterChart } from "insightcharts";

const data = [
  { country: "United States", spend: 12555, life: 77.5 },
  { country: "Switzerland", spend: 8049, life: 83.9 },
  { country: "Germany", spend: 8011, life: 80.8 },
  { country: "Norway", spend: 7771, life: 83.2 },
  { country: "Netherlands", spend: 6729, life: 81.4 },
  { country: "France", spend: 6630, life: 82.4 },
  { country: "Canada", spend: 6319, life: 81.6 },
  { country: "Sweden", spend: 6438, life: 83.1 },
  { country: "Australia", spend: 6372, life: 83.3 },
  { country: "United Kingdom", spend: 5493, life: 80.7 },
  { country: "Japan", spend: 5251, life: 84.5 },
  { country: "Italy", spend: 4291, life: 82.7 },
  { country: "Spain", spend: 4432, life: 83.3 },
  { country: "South Korea", spend: 4570, life: 83.6 },
  { country: "Portugal", spend: 4162, life: 81.5 },
  { country: "Israel", spend: 3444, life: 82.6 },
  { country: "Poland", spend: 2973, life: 76.5 },
  { country: "Chile", spend: 2699, life: 81 },
  { country: "Mexico", spend: 1181, life: 75.4 },
];

<ScatterChart
  data={data}
  x="spend"
  y="life"
  label="country"
  highlight="United States"
  labels={["United States", "Japan", "Mexico", "Switzerland", "Poland"]}
  xFormat="currency:USD"
  xLabel="Health spending per person"
  yLabel="Life expectancy, years"
  title="The United States spent $12,555 per person on health in 2022"
  subtitle="Health spending per person (US$, PPP) against life expectancy at birth, OECD countries, 2022. US life expectancy was 77.5 years."
  source="OECD Health Statistics (rounded)"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "scatter-chart",
  "data": [
    { "country": "United States", "spend": 12555, "life": 77.5 },
    { "country": "Switzerland", "spend": 8049, "life": 83.9 },
    { "country": "Germany", "spend": 8011, "life": 80.8 },
    { "country": "Norway", "spend": 7771, "life": 83.2 },
    { "country": "Netherlands", "spend": 6729, "life": 81.4 },
    { "country": "France", "spend": 6630, "life": 82.4 },
    { "country": "Canada", "spend": 6319, "life": 81.6 },
    { "country": "Sweden", "spend": 6438, "life": 83.1 },
    { "country": "Australia", "spend": 6372, "life": 83.3 },
    { "country": "United Kingdom", "spend": 5493, "life": 80.7 },
    { "country": "Japan", "spend": 5251, "life": 84.5 },
    { "country": "Italy", "spend": 4291, "life": 82.7 },
    { "country": "Spain", "spend": 4432, "life": 83.3 },
    { "country": "South Korea", "spend": 4570, "life": 83.6 },
    { "country": "Portugal", "spend": 4162, "life": 81.5 },
    { "country": "Israel", "spend": 3444, "life": 82.6 },
    { "country": "Poland", "spend": 2973, "life": 76.5 },
    { "country": "Chile", "spend": 2699, "life": 81 },
    { "country": "Mexico", "spend": 1181, "life": 75.4 }
  ],
  "x": "spend",
  "y": "life",
  "label": "country",
  "highlight": "United States",
  "labels": ["United States", "Japan", "Mexico", "Switzerland", "Poland"],
  "xFormat": "currency:USD",
  "xLabel": "Health spending per person",
  "yLabel": "Life expectancy, years",
  "title": "The United States spent $12,555 per person on health in 2022",
  "subtitle": "Health spending per person (US$, PPP) against life expectancy at birth, OECD countries, 2022. US life expectancy was 77.5 years.",
  "source": "OECD Health Statistics (rounded)",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `x` (required) | `string` |  | Numeric field on the horizontal axis. |
| `y` (required) | `string` |  | Numeric field on the vertical axis. |
| `size` | `string` |  | Numeric field for bubble size; area is proportional to the value. |
| `series` | `string` |  | Field that colours points by group. Beyond 4 groups the smallest fold into a grey Other. |
| `label` | `string` |  | Field naming each point, for tooltips, direct labels and `highlight`. |
| `labels` | `"auto" \| "all" \| "none" \| string[]` | `"auto"` | Which points are labelled. `auto`: highlighted points, or the outliers when nothing is highlighted. Overlapping labels are hidden. |
| `trend` | `boolean` | `false` | Least-squares line of best fit through all points. |
| `logX` | `boolean` | `false` | Logarithmic x axis. |
| `logY` | `boolean` | `false` | Logarithmic y axis. |
| `xLabel` | `string` |  | x axis title. Defaults to the field name. |
| `yLabel` | `string` |  | y axis title. Defaults to the field name. |
| `xFormat` | `FormatSpec` |  | Format for x values; `format` applies to y. |
| `opacity` | `number` |  | Point opacity. Default falls as the point count rises. |
| `names` | `Record<string, string>` |  | Display names for series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Bubbles, colour groups, log axis

```tsx
import { ScatterChart } from "insightcharts";

const data = [
  { country: "Africa 1", region: "Africa", gdp: 2494, life: 61.3, pop: 24.6 },
  { country: "Africa 2", region: "Africa", gdp: 1050, life: 58.4, pop: 61.2 },
  { country: "Africa 3", region: "Africa", gdp: 3104, life: 60.2, pop: 6 },
  { country: "Africa 4", region: "Africa", gdp: 1841, life: 61.4, pop: 1439.1 },
  { country: "Africa 5", region: "Africa", gdp: 3381, life: 65.6, pop: 4.9 },
  { country: "Africa 6", region: "Africa", gdp: 1226, life: 64.3, pop: 136.3 },
  { country: "Africa 7", region: "Africa", gdp: 1115, life: 63.8, pop: 38.6 },
  { country: "Africa 8", region: "Africa", gdp: 4996, life: 66.4, pop: 12 },
  // ... 96 more rows
];

<ScatterChart
  data={data}
  x="gdp"
  y="life"
  size="pop"
  series="region"
  label="country"
  logX
  xFormat="currency:USD"
  xLabel="GDP per person"
  yLabel="Life expectancy, years"
  title="GDP per person and life expectancy, 104 countries"
  subtitle="GDP per person (US$, log scale) against life expectancy. Bubble area is population."
  note="Illustrative data"
/>
```

#### Quadrants via annotations

```tsx
import { ScatterChart } from "insightcharts";

const data = [
  { feature: "Search", usage: 82, satisfaction: 4.4 },
  { feature: "Dashboards", usage: 74, satisfaction: 3.1 },
  { feature: "Exports", usage: 61, satisfaction: 2.6 },
  { feature: "Alerts", usage: 48, satisfaction: 4.1 },
  { feature: "API", usage: 22, satisfaction: 4.5 },
  { feature: "Comments", usage: 31, satisfaction: 3.4 },
  { feature: "Mobile app", usage: 39, satisfaction: 2.2 },
  { feature: "SSO", usage: 18, satisfaction: 3.9 },
  // ... 2 more rows
];

<ScatterChart
  data={data}
  x="usage"
  y="satisfaction"
  label="feature"
  labels="all"
  highlight={["Exports", "Dashboards"]}
  xFormat="{value}%"
  xLabel="Weekly active users who use it"
  yLabel="Satisfaction, 1 to 5"
  annotations={[
    { type: "line", axis: "x", value: 50, label: "Widely used" },
    { type: "line", axis: "y", value: 3.5, label: "Liked" },
  ]}
  title="Exports is used by 61% of weekly users and rated 2.6 out of 5"
  subtitle="Share of weekly users against mean satisfaction, by feature. Dashboards is used by 74% and rated 3.1."
  note="Illustrative data"
/>
```

#### Stress: 2,400 points with a trend

```tsx
import { ScatterChart } from "insightcharts";

const data = [
  { id: "Sale 1", sqm: 120, price: 359 },
  { id: "Sale 2", sqm: 95, price: 314 },
  { id: "Sale 3", sqm: 147, price: 437 },
  { id: "Sale 4", sqm: 100, price: 319 },
  { id: "Sale 5", sqm: 66, price: 183 },
  { id: "Sale 6", sqm: 109, price: 199 },
  { id: "Sale 7", sqm: 123, price: 479 },
  { id: "Sale 8", sqm: 133, price: 403 },
  // ... 2392 more rows
];

<ScatterChart
  data={data}
  x="sqm"
  y="price"
  label="id"
  labels="none"
  trend
  xFormat="{value} m²"
  format="{value}k"
  xLabel="Floor area"
  yLabel="Sale price, thousands"
  title="Floor area and sale price, 2,400 home sales"
  subtitle="Floor area in m² against sale price in thousands, with a least-squares trend line"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/scatter-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/scatter-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Segmented bar (`segmented-bar`)

> Splits one whole into proportional segments along a single horizontal bar.

- Component: `SegmentedBar` (import from `insightcharts`)
- Spec type: `"segmented-bar"`
- Level: atom. Category: part-to-whole.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

A compact part-to-whole for cards, table cells and stat rows: budget split, device mix, vote share. The legend carries names in block order.

### Avoid

Comparing compositions across several groups (use bar-chart with stack "percent"); more than about 6 parts or many slivers (use bar-chart); when the reader should count units (use waffle-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/segmented-bar
```

The file lands at `components/insightcharts/atoms/segmented-bar.tsx`. `@insightcharts/segmented-bar-demo` adds a ready-made example next to it.

### Usage

```tsx
import { SegmentedBar } from "insightcharts";

const data = [
  { party: "Labour", seats: 411 },
  { party: "Conservative", seats: 121 },
  { party: "Liberal Democrat", seats: 72 },
  { party: "SNP", seats: 9 },
  { party: "Others", seats: 37 },
];

<SegmentedBar
  data={data}
  name="party"
  value="seats"
  title="Labour won 411 of 650 seats in the 2024 general election"
  subtitle="Seats in the House of Commons by party after the 2024 general election"
  source="House of Commons Library"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "segmented-bar",
  "data": [
    { "party": "Labour", "seats": 411 },
    { "party": "Conservative", "seats": 121 },
    { "party": "Liberal Democrat", "seats": 72 },
    { "party": "SNP", "seats": 9 },
    { "party": "Others", "seats": 37 }
  ],
  "name": "party",
  "value": "seats",
  "title": "Labour won 411 of 650 seats in the 2024 general election",
  "subtitle": "Seats in the House of Commons by party after the 2024 general election",
  "source": "House of Commons Library",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Category field: one segment per distinct value. |
| `value` (required) | `string` |  | Value field. |
| `size` | `"tall" \| "thin"` | `"tall"` | 28px with shares printed inside where they fit, or 8px unlabelled. |
| `sort` | `"none" \| "desc"` | `"none"` | Segment order; the legend follows it. |
| `names` | `Record<string, string>` |  | Display names for category keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [metric-breakdown](https://insightcharts.dev/llms/metric-breakdown.md), [poster](https://insightcharts.dev/llms/poster.md), [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md), [explainer](https://insightcharts.dev/llms/explainer.md)

### More examples

#### Thin, for cards

```tsx
import { SegmentedBar } from "insightcharts";

const data = [
  { device: "Mobile", sessions: 58200 },
  { device: "Desktop", sessions: 31400 },
  { device: "Tablet", sessions: 6100 },
];

<SegmentedBar
  data={data}
  name="device"
  value="sessions"
  size="thin"
  title="Mobile accounted for 61% of sessions in the last 30 days"
  subtitle="Sessions by device, last 30 days"
/>
```

#### With highlight

```tsx
import { SegmentedBar } from "insightcharts";

const data = [
  { item: "Housing", spend: 33 },
  { item: "Transport", spend: 17 },
  { item: "Food", spend: 13 },
  { item: "Healthcare", spend: 8 },
  { item: "Everything else", spend: 29 },
];

<SegmentedBar
  data={data}
  name="item"
  value="spend"
  highlight="Housing"
  title="Housing was 33% of US consumer spending in 2023"
  subtitle="Share of annual consumer spending, United States, 2023"
  source="BLS Consumer Expenditure Survey"
  note="Figures are approximate, for illustration"
/>
```

#### Stress: many parts, long names, slivers

```tsx
import { SegmentedBar } from "insightcharts";

const data = [
  { cause: "Cardiovascular diseases", deaths: 19.8 },
  { cause: "Cancers", deaths: 10 },
  { cause: "Chronic respiratory diseases", deaths: 4 },
  { cause: "Digestive diseases", deaths: 2.6 },
  { cause: "Lower respiratory infections", deaths: 2.2 },
  { cause: "Neonatal disorders", deaths: 1.8 },
  { cause: "Alzheimer's disease and other dementias", deaths: 1.8 },
  { cause: "Diabetes", deaths: 1.6 },
  // ... 3 more rows
];

<SegmentedBar
  data={data}
  name="cause"
  value="deaths"
  format="{value}m"
  title="Cardiovascular diseases cause 19.8 million deaths a year"
  subtitle="Deaths by cause, world, millions per year"
  source="IHME Global Burden of Disease"
  note="Rounded, approximate figures for illustration"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/segmented-bar.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/segmented-bar.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Shape fill (`shape-fill`)

> Shows one or more percentages as icon silhouettes filled from the bottom to that level, with the number printed large beside each.

- Component: `ShapeFill` (import from `insightcharts`)
- Spec type: `"shape-fill"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

One to six shares of a full amount where the object itself says what is measured: how full a reservoir is, how charged a fleet is, what share of homes have a heat pump.

### Avoid

The fill height only approximates the share, because an irregular silhouette holds less area at its narrow end, so the number must always stay printed; for values to be compared precisely use block-bar or bar-chart, for a counted share use waffle-chart, for a compact inline meter use progress-meter.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/shape-fill
```

The file lands at `components/insightcharts/atoms/shape-fill.tsx`. `@insightcharts/shape-fill-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ShapeFill } from "insightcharts";

const data = [
  { reservoir: "Carrow", level: 63 },
  { reservoir: "Upper Fen", level: 41 },
  { reservoir: "Stonebeck", level: 88 },
];

<ShapeFill
  data={data}
  name="reservoir"
  value="level"
  icon="drop"
  format="{value}%"
  title="Carrow Reservoir was 63% full on 1 September 2025"
  subtitle="Water stored as a share of capacity, three reservoirs, 1 September 2025"
  source="Illustrative data"
  note="Invented figures for fictional reservoirs"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "shape-fill",
  "data": [
    { "reservoir": "Carrow", "level": 63 },
    { "reservoir": "Upper Fen", "level": 41 },
    { "reservoir": "Stonebeck", "level": 88 }
  ],
  "name": "reservoir",
  "value": "level",
  "icon": "drop",
  "format": "{value}%",
  "title": "Carrow Reservoir was 63% full on 1 September 2025",
  "subtitle": "Water stored as a share of capacity, three reservoirs, 1 September 2025",
  "source": "Illustrative data",
  "note": "Invented figures for fictional reservoirs"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Label field: one silhouette per row. |
| `value` (required) | `string` |  | Value field: how full each silhouette is, against `max`. |
| `max` | `number` |  | The value that fills a silhouette completely. Default: 1 when every value is at most 1, otherwise 100. |
| `icon` | `IconName \| "path://..."` | `"drop"` | Built-in icon name or a custom single SVG path. |
| `icons` | `Record<string, string>` |  | Icon per label; falls back to `icon`. |
| `columns` | `number` |  | Silhouettes per line. Default: up to four, two on a phone. |
| `colorBy` | `"single" \| "item"` | `"single"` | `single`: every silhouette in the accent colour. `item`: one colour per row. |
| `iconSize` | `number` |  | Silhouette height in px. Default: sized to the width, or grown to fill the box when the `height` prop or `aspect` is given, so one silhouette can be the main figure of a poster. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [count-poster](https://insightcharts.dev/llms/count-poster.md), [profile-poster](https://insightcharts.dev/llms/profile-poster.md), [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md)

### More examples

#### One silhouette

```tsx
import { ShapeFill } from "insightcharts";

const data = [{ what: "of homes in Eastvale had a heat pump", share: 0.18 }];

<ShapeFill
  data={data}
  name="what"
  value="share"
  icon="house"
  format="percent"
  title="18% of homes in Eastvale had a heat pump in 2025"
  subtitle="Share of occupied homes with a heat pump installed, 2025"
  source="Illustrative data"
  note="Invented figure for a fictional town"
/>
```

#### One silhouette sized by the height prop

```tsx
import { ShapeFill } from "insightcharts";

const data = [{ what: "of the battery fleet was charged at 6am", share: 0.72 }];

<ShapeFill
  data={data}
  name="what"
  value="share"
  icon="bolt"
  format="percent"
  height={460}
  title="72% of the battery fleet was charged at 6am on 3 March 2025"
  subtitle="Share of 140 electric buses with a full charge at the start of service"
  source="Illustrative data"
  note="Invented figure for a fictional operator"
/>
```

#### Highlight, click to select

```tsx
import { ShapeFill } from "insightcharts";

const data = [
  { district: "Northbank", cover: 34 },
  { district: "Old Town", cover: 9 },
  { district: "Riverside", cover: 22 },
  { district: "Hillcrest", cover: 47 },
];

<ShapeFill
  data={data}
  name="district"
  value="cover"
  icon="tree"
  format="{value}%"
  highlight="Old Town"
  select
  title="Trees covered 9% of Old Town in 2025"
  subtitle="Tree canopy as a share of land area by district, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional city"
/>
```

#### Stress: six items, mixed icons, long labels

```tsx
import { ShapeFill } from "insightcharts";

const data = [
  { item: "Electric buses charged and ready at 6am", ready: 92 },
  { item: "Households on a time-of-use electricity tariff", ready: 27 },
  { item: "Company cars that are battery electric", ready: 54 },
  { item: "Street trees surviving their first five years", ready: 71 },
  { item: "Reservoir storage", ready: 3 },
  { item: "Adults with a savings account", ready: 100 },
];

<ShapeFill
  data={data}
  name="item"
  value="ready"
  icons={{
    "Electric buses charged and ready at 6am": "bolt",
    "Households on a time-of-use electricity tariff": "house",
    "Company cars that are battery electric": "car",
    "Street trees surviving their first five years": "tree",
    "Reservoir storage": "drop",
    "Adults with a savings account": "person",
  }}
  columns={3}
  colorBy="item"
  format="{value}%"
  title="Six shares from the 2025 city report"
  subtitle="Each silhouette is filled to the share shown beside it"
  source="Illustrative data"
  note="Invented figures"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/shape-fill.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/shape-fill.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Slope chart (`slope-chart`)

> Connects each entity's value at two (or a few) points with a straight line, labelled with name and value at both ends.

- Component: `SlopeChart` (import from `insightcharts`)
- Spec type: `"slope-chart"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Before / after for 3 to about 15 entities when the change in level and in ordering both matter; pair with `highlight` to emphasise one line.

### Avoid

Five or more time points (use line-chart); when only the ordering matters (use bump-chart); when only the size of each gap matters (use dumbbell-chart or arrow-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/slope-chart
```

The file lands at `components/insightcharts/atoms/slope-chart.tsx`. `@insightcharts/slope-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { SlopeChart } from "insightcharts";

const data = [
  { country: "United Kingdom", y2012: 39, y2023: 1 },
  { country: "Germany", y2012: 44, y2023: 26 },
  { country: "United States", y2012: 37, y2023: 16 },
  { country: "Poland", y2012: 84, y2023: 61 },
  { country: "India", y2012: 71, y2023: 75 },
  { country: "Japan", y2012: 29, y2023: 32 },
];

<SlopeChart
  data={data}
  series="country"
  y={["y2012", "y2023"]}
  names={{ y2012: "2012", y2023: "2023" }}
  highlight="United Kingdom"
  format="{value}%"
  title="The UK's coal share of electricity fell from 39% to 1% between 2012 and 2023"
  subtitle="Share of electricity generated from coal, 2012 and 2023"
  source="Ember (rounded)"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "slope-chart",
  "data": [
    { "country": "United Kingdom", "y2012": 39, "y2023": 1 },
    { "country": "Germany", "y2012": 44, "y2023": 26 },
    { "country": "United States", "y2012": 37, "y2023": 16 },
    { "country": "Poland", "y2012": 84, "y2023": 61 },
    { "country": "India", "y2012": 71, "y2023": 75 },
    { "country": "Japan", "y2012": 29, "y2023": 32 }
  ],
  "series": "country",
  "y": ["y2012", "y2023"],
  "names": { "y2012": "2012", "y2023": "2023" },
  "highlight": "United Kingdom",
  "format": "{value}%",
  "title": "The UK's coal share of electricity fell from 39% to 1% between 2012 and 2023",
  "subtitle": "Share of electricity generated from coal, 2012 and 2023",
  "source": "Ember (rounded)",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `series` (required) | `string` |  | Entity field: one line each. |
| `x` | `string` |  | Period field for long data. Omit when each row is an entity with one column per period. |
| `y` (required) | `string \| string[]` |  | Value field (long data), or the period columns in order (one row per entity). |
| `colorBy` | `"none" \| "direction" \| "series"` | `"none"` | Accent for all lines, positive / negative by direction, or one hue per entity (up to 8). |
| `good` | `"up" \| "down"` | `"up"` | Direction that takes the positive colour when colouring by direction. |
| `labels` | `"both" \| "end"` |  | Entity names at both ends or only the end. Default: both; end only on narrow screens. |
| `names` | `Record<string, string>` |  | Display names for entity keys and period columns. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md)

### More examples

#### Coloured by direction

```tsx
import { SlopeChart } from "insightcharts";

const data = [
  { region: "North East", before: 71.2, after: 68.4 },
  { region: "London", before: 68.9, after: 75.1 },
  { region: "South West", before: 76, after: 77.8 },
  { region: "Wales", before: 69.5, after: 72.6 },
  { region: "Scotland", before: 73.4, after: 73.1 },
  { region: "West Midlands", before: 70.1, after: 73.9 },
];

<SlopeChart
  data={data}
  series="region"
  y={["before", "after"]}
  names={{ before: "2014", after: "2024" }}
  colorBy="direction"
  format="{value}%"
  title="London's employment rate rose from 68.9% to 75.1% between 2014 and 2024"
  subtitle="Employment rate, ages 16 to 64, 2014 and 2024"
  note="Illustrative figures."
/>
```

#### Long format, three periods

```tsx
import { SlopeChart } from "insightcharts";

const data = [
  { format: "Streaming", year: "2012", share: 9 },
  { format: "Streaming", year: "2016", share: 34 },
  { format: "Streaming", year: "2023", share: 67 },
  { format: "Physical", year: "2012", share: 52 },
  { format: "Physical", year: "2016", share: 31 },
  { format: "Physical", year: "2023", share: 11 },
  { format: "Downloads", year: "2012", share: 31 },
  { format: "Downloads", year: "2016", share: 24 },
  // ... 4 more rows
];

<SlopeChart
  data={data}
  series="format"
  x="year"
  y="share"
  colorBy="series"
  format="{value}%"
  height={320}
  title="Streaming's share of recorded music revenue rose from 9% to 67% between 2012 and 2023"
  subtitle="Share of recorded music revenue by format, 2012, 2016 and 2023"
  note="Illustrative figures."
/>
```

#### Stress: 20 entities with close values and long names

```tsx
import { SlopeChart } from "insightcharts";

const data = [
  { country: "Democratic Republic of the Congo", y2000: 41, y2022: 62 },
  { country: "United Republic of Tanzania", y2000: 44, y2022: 58 },
  { country: "Central African Republic", y2000: 40, y2022: 43 },
  { country: "Papua New Guinea", y2000: 47, y2022: 49 },
  { country: "Bosnia and Herzegovina", y2000: 71, y2022: 70 },
  { country: "Saint Vincent and the Grenadines", y2000: 69, y2022: 71 },
  { country: "Trinidad and Tobago", y2000: 68, y2022: 66 },
  { country: "Lao People's Democratic Republic", y2000: 52, y2022: 66 },
  // ... 12 more rows
];

<SlopeChart
  data={data}
  series="country"
  y={["y2000", "y2022"]}
  names={{ y2000: "2000", y2022: "2022" }}
  highlight={["Ethiopia", "Bangladesh"]}
  height={520}
  title="Life expectancy in Ethiopia rose from 39 to 65 years between 2000 and 2022"
  subtitle="Life expectancy at birth, years, 2000 and 2022. Bangladesh rose from 49 to 73."
  note="Illustrative figures."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/slope-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/slope-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Small multiples (`small-multiples`)

> Repeats one small line, area or bar chart per value of a facet field on a shared scale, each panel titled.

- Component: `SmallMultiples` (import from `insightcharts`)
- Spec type: `"small-multiples"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

The same measure for 4 to about 24 entities when one chart would have too many overlapping lines; pair with `highlight` to pick out one panel, or `context` to show every other line faintly behind each.

### Avoid

Three or fewer series (use line-chart with direct labels); when exact comparison between two entities matters most (use line-chart with `highlight`); a single value per entity (use bar-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/small-multiples
```

The file lands at `components/insightcharts/atoms/small-multiples.tsx`. `@insightcharts/small-multiples-demo` adds a ready-made example next to it.

### Usage

```tsx
import { SmallMultiples } from "insightcharts";

const data = [
  { country: "Germany", year: "2010", rate: 6.8 },
  { country: "Germany", year: "2013", rate: 5 },
  { country: "Germany", year: "2015", rate: 4.6 },
  { country: "Germany", year: "2017", rate: 3.8 },
  { country: "Germany", year: "2019", rate: 3.1 },
  { country: "Germany", year: "2021", rate: 3.6 },
  { country: "Germany", year: "2023", rate: 3 },
  { country: "Germany", year: "2024", rate: 3.4 },
  { country: "Spain", year: "2010", rate: 19.9 },
  { country: "Spain", year: "2013", rate: 26.1 },
  { country: "Spain", year: "2015", rate: 22.1 },
  { country: "Spain", year: "2017", rate: 17.2 },
  { country: "Spain", year: "2019", rate: 14.1 },
  { country: "Spain", year: "2021", rate: 14.8 },
  { country: "Spain", year: "2023", rate: 12.2 },
  { country: "Spain", year: "2024", rate: 11.4 },
  { country: "Italy", year: "2010", rate: 8.4 },
  { country: "Italy", year: "2013", rate: 12.1 },
  { country: "Italy", year: "2015", rate: 11.9 },
  { country: "Italy", year: "2017", rate: 11.2 },
  { country: "Italy", year: "2019", rate: 9.9 },
  { country: "Italy", year: "2021", rate: 9.5 },
  { country: "Italy", year: "2023", rate: 7.7 },
  { country: "Italy", year: "2024", rate: 6.5 },
  { country: "France", year: "2010", rate: 9.3 },
  { country: "France", year: "2013", rate: 10.3 },
  { country: "France", year: "2015", rate: 10.4 },
  { country: "France", year: "2017", rate: 9.4 },
  { country: "France", year: "2019", rate: 8.4 },
  { country: "France", year: "2021", rate: 7.9 },
  { country: "France", year: "2023", rate: 7.3 },
  { country: "France", year: "2024", rate: 7.4 },
  { country: "Greece", year: "2010", rate: 12.7 },
  { country: "Greece", year: "2013", rate: 27.5 },
  { country: "Greece", year: "2015", rate: 24.9 },
  { country: "Greece", year: "2017", rate: 21.5 },
  { country: "Greece", year: "2019", rate: 17.3 },
  { country: "Greece", year: "2021", rate: 14.7 },
  { country: "Greece", year: "2023", rate: 11.1 },
  { country: "Greece", year: "2024", rate: 10.1 },
  { country: "Poland", year: "2010", rate: 9.7 },
  { country: "Poland", year: "2013", rate: 10.3 },
  { country: "Poland", year: "2015", rate: 7.5 },
  { country: "Poland", year: "2017", rate: 4.9 },
  { country: "Poland", year: "2019", rate: 3.3 },
  { country: "Poland", year: "2021", rate: 3.4 },
  { country: "Poland", year: "2023", rate: 2.8 },
  { country: "Poland", year: "2024", rate: 2.9 },
];

<SmallMultiples
  data={data}
  facet="country"
  x="year"
  y="rate"
  highlight="Greece"
  format="{value}%"
  title="Greek unemployment fell from 27.5% in 2013 to 10.1% in 2024"
  subtitle="Unemployment rate, 2010 to 2024, same scale in every panel"
  source="Eurostat (rounded)"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "small-multiples",
  "data": [
    { "country": "Germany", "year": "2010", "rate": 6.8 },
    { "country": "Germany", "year": "2013", "rate": 5 },
    { "country": "Germany", "year": "2015", "rate": 4.6 },
    { "country": "Germany", "year": "2017", "rate": 3.8 },
    { "country": "Germany", "year": "2019", "rate": 3.1 },
    { "country": "Germany", "year": "2021", "rate": 3.6 },
    { "country": "Germany", "year": "2023", "rate": 3 },
    { "country": "Germany", "year": "2024", "rate": 3.4 },
    { "country": "Spain", "year": "2010", "rate": 19.9 },
    { "country": "Spain", "year": "2013", "rate": 26.1 },
    { "country": "Spain", "year": "2015", "rate": 22.1 },
    { "country": "Spain", "year": "2017", "rate": 17.2 },
    { "country": "Spain", "year": "2019", "rate": 14.1 },
    { "country": "Spain", "year": "2021", "rate": 14.8 },
    { "country": "Spain", "year": "2023", "rate": 12.2 },
    { "country": "Spain", "year": "2024", "rate": 11.4 },
    { "country": "Italy", "year": "2010", "rate": 8.4 },
    { "country": "Italy", "year": "2013", "rate": 12.1 },
    { "country": "Italy", "year": "2015", "rate": 11.9 },
    { "country": "Italy", "year": "2017", "rate": 11.2 },
    { "country": "Italy", "year": "2019", "rate": 9.9 },
    { "country": "Italy", "year": "2021", "rate": 9.5 },
    { "country": "Italy", "year": "2023", "rate": 7.7 },
    { "country": "Italy", "year": "2024", "rate": 6.5 },
    { "country": "France", "year": "2010", "rate": 9.3 },
    { "country": "France", "year": "2013", "rate": 10.3 },
    { "country": "France", "year": "2015", "rate": 10.4 },
    { "country": "France", "year": "2017", "rate": 9.4 },
    { "country": "France", "year": "2019", "rate": 8.4 },
    { "country": "France", "year": "2021", "rate": 7.9 },
    { "country": "France", "year": "2023", "rate": 7.3 },
    { "country": "France", "year": "2024", "rate": 7.4 },
    { "country": "Greece", "year": "2010", "rate": 12.7 },
    { "country": "Greece", "year": "2013", "rate": 27.5 },
    { "country": "Greece", "year": "2015", "rate": 24.9 },
    { "country": "Greece", "year": "2017", "rate": 21.5 },
    { "country": "Greece", "year": "2019", "rate": 17.3 },
    { "country": "Greece", "year": "2021", "rate": 14.7 },
    { "country": "Greece", "year": "2023", "rate": 11.1 },
    { "country": "Greece", "year": "2024", "rate": 10.1 },
    { "country": "Poland", "year": "2010", "rate": 9.7 },
    { "country": "Poland", "year": "2013", "rate": 10.3 },
    { "country": "Poland", "year": "2015", "rate": 7.5 },
    { "country": "Poland", "year": "2017", "rate": 4.9 },
    { "country": "Poland", "year": "2019", "rate": 3.3 },
    { "country": "Poland", "year": "2021", "rate": 3.4 },
    { "country": "Poland", "year": "2023", "rate": 2.8 },
    { "country": "Poland", "year": "2024", "rate": 2.9 }
  ],
  "facet": "country",
  "x": "year",
  "y": "rate",
  "highlight": "Greece",
  "format": "{value}%",
  "title": "Greek unemployment fell from 27.5% in 2013 to 10.1% in 2024",
  "subtitle": "Unemployment rate, 2010 to 2024, same scale in every panel",
  "source": "Eurostat (rounded)",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `facet` (required) | `string` |  | Field whose values each get a panel. |
| `x` (required) | `string` |  | Time or ordered category field, shared by every panel. |
| `y` (required) | `string \| string[]` |  | Value field, or several (one series each in every panel). |
| `series` | `string` |  | Field that splits rows into series inside each panel (long data). |
| `kind` | `"line" \| "area" \| "bar"` | `"line"` | What each panel draws. Area and bar panels start at zero. |
| `columns` | `number` |  | Preferred number of columns; reduced automatically on narrow containers. |
| `scales` | `"shared" \| "free"` | `"shared"` | Shared value scale across panels, or each panel on its own (say so in the subtitle). |
| `context` | `boolean` | `false` | Draw every other panel's line faintly behind each panel's own. |
| `latest` | `boolean` |  | Print the latest value beside each panel title. Default: on for a single series. |
| `names` | `Record<string, string>` |  | Display names for facet values and series keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Every other line as context

```tsx
import { SmallMultiples } from "insightcharts";

const data = [
  { city: "Phoenix", month: "Jan", temp: 12.4 },
  { city: "Phoenix", month: "Feb", temp: 14.1 },
  { city: "Phoenix", month: "Mar", temp: 17.6 },
  { city: "Phoenix", month: "Apr", temp: 22.8 },
  { city: "Phoenix", month: "May", temp: 27.9 },
  { city: "Phoenix", month: "Jun", temp: 31.2 },
  { city: "Phoenix", month: "Jul", temp: 33 },
  { city: "Phoenix", month: "Aug", temp: 31.8 },
  // ... 88 more rows
];

<SmallMultiples
  data={data}
  facet="city"
  x="month"
  y="temp"
  context
  format="{value}°"
  height={380}
  title="Chicago's average monthly temperature ranges from -3.2°C to 24.3°C"
  subtitle="Average monthly temperature, °C. Honolulu ranges from 23.0 to 27.9. Grey lines show the other cities."
  source="NOAA climate normals (rounded)"
  note="Figures are approximate, for illustration"
/>
```

#### Bars, two series per panel (wide data)

```tsx
import { SmallMultiples } from "insightcharts";

const data = [
  { region: "North", quarter: "Q1", store: 42, online: 31 },
  { region: "North", quarter: "Q2", store: 48, online: 36 },
  { region: "North", quarter: "Q3", store: 55, online: 39 },
  { region: "North", quarter: "Q4", store: 61, online: 44 },
  { region: "South", quarter: "Q1", store: 28, online: 30 },
  { region: "South", quarter: "Q2", store: 31, online: 34 },
  { region: "South", quarter: "Q3", store: 33, online: 39 },
  { region: "South", quarter: "Q4", store: 36, online: 45 },
  // ... 8 more rows
];

<SmallMultiples
  data={data}
  facet="region"
  x="quarter"
  y={["store", "online"]}
  names={{ store: "In store", online: "Online" }}
  kind="bar"
  format="currency:USD"
  height={300}
  title="The South sold $45 million online and $36 million in store in Q4"
  subtitle="Quarterly sales by channel, $ millions"
  note="Illustrative figures."
/>
```

#### Stress: 20 panels with long titles

```tsx
import { SmallMultiples } from "insightcharts";

const data = [
  { country: "United States of America", year: "2013", index: 100 },
  { country: "United States of America", year: "2014", index: 101 },
  { country: "United States of America", year: "2015", index: 96 },
  { country: "United States of America", year: "2016", index: 91 },
  { country: "United States of America", year: "2017", index: 92 },
  { country: "United States of America", year: "2018", index: 87 },
  { country: "United States of America", year: "2019", index: 82 },
  { country: "United States of America", year: "2020", index: 71 },
  // ... 232 more rows
];

<SmallMultiples
  data={data}
  facet="country"
  x="year"
  y="index"
  kind="area"
  highlight={["India", "Indonesia"]}
  height={560}
  title="Illustrative index for 20 countries, 2013 to 2024"
  subtitle="Index, 2013 = 100. All panels share the same axes."
  note="Synthetic data for layout testing."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/small-multiples.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/small-multiples.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Source note (`source-note`)

> A sourcing footer for a whole piece: sources with optional links, the period covered, method, caveats and credit.

- Component: `SourceNote` (import from `insightcharts`)
- Spec type: `"source-note"`
- Level: atom. Category: text.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Once, at the end of a story or dashboard, to say where every number came from and how it was produced.

### Avoid

Sourcing a single chart: use that chart's own `source` and `note` props so the citation travels with its export.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/source-note
```

The file lands at `components/insightcharts/atoms/source-note.tsx`. `@insightcharts/source-note-demo` adds a ready-made example next to it.

### Usage

```tsx
import { SourceNote } from "insightcharts";

<SourceNote
  sources={[
    { name: "Ember, European Electricity Review 2025", url: "https://ember-energy.org" },
    { name: "ENTSO-E Transparency Platform", url: "https://transparency.entsoe.eu" },
  ]}
  note="Figures are approximate, for illustration"
  period="January 2015 to December 2024, monthly"
  method="Generation shares are net of pumped-storage consumption. Figures for 2024 are provisional and exclude Malta and Cyprus."
  credit="Analysis and charts by the data desk"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "source-note",
  "sources": [
    { "name": "Ember, European Electricity Review 2025", "url": "https://ember-energy.org" },
    { "name": "ENTSO-E Transparency Platform", "url": "https://transparency.entsoe.eu" }
  ],
  "note": "Figures are approximate, for illustration",
  "period": "January 2015 to December 2024, monthly",
  "method": "Generation shares are net of pumped-storage consumption. Figures for 2024 are provisional and exclude Malta and Cyprus.",
  "credit": "Analysis and charts by the data desk"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers, e.g. "2015 to 2024". Shown as "Data". |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know. |
| `credit` | `string` |  | Who made the piece. |
| `layout` | `"list" \| "inline"` | `"list"` | Labelled list, or one running paragraph. |
| `rule` | `boolean` | `true` | Hairline above the note. |
| `children` | `ReactNode` |  | Extra content after the rows. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [hero-figure](https://insightcharts.dev/llms/hero-figure.md), [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md), [data-explorer](https://insightcharts.dev/llms/data-explorer.md), [executive-brief](https://insightcharts.dev/llms/executive-brief.md), [explainer](https://insightcharts.dev/llms/explainer.md), [report-page](https://insightcharts.dev/llms/report-page.md), [scorecard](https://insightcharts.dev/llms/scorecard.md), [social-card](https://insightcharts.dev/llms/social-card.md), [story-deck](https://insightcharts.dev/llms/story-deck.md), [timeline-story](https://insightcharts.dev/llms/timeline-story.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Inline

```tsx
import { SourceNote } from "insightcharts";

<SourceNote
  layout="inline"
  sources={["Office for National Statistics", "Ofgem price cap tables"]}
  note="Figures are approximate, for illustration"
  period="Q1 2019 to Q4 2024"
  method="Bills are for a typical dual-fuel household paying by direct debit, in 2024 prices"
  credit="Chart design: A. Ruiz"
/>
```

#### Single source, no rule

```tsx
import { SourceNote } from "insightcharts";

<SourceNote
  rule={false}
  sources="World Bank, World Development Indicators"
  note="Illustrative data for the gallery."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/source-note.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/source-note.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Sparkline (`sparkline`)

> A word-sized line or bar series without axes, with the latest point marked.

- Component: `Sparkline` (import from `insightcharts`)
- Spec type: `"sparkline"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Showing the recent history of a number inside a stat tile, a table cell or a sentence, where the shape of the trend matters and exact values do not.

### Avoid

Anything the reader must read values from or compare across series (use line-chart); fewer than about 5 points (state the change in words or use big-number with a delta).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/sparkline
```

The file lands at `components/insightcharts/atoms/sparkline.tsx`. `@insightcharts/sparkline-demo` adds a ready-made example next to it.

### Usage

```tsx
import { Sparkline } from "insightcharts";

const data = [
  { month: "2023-07", rate: 3.9 },
  { month: "2023-08", rate: 3.8 },
  { month: "2023-09", rate: 3.8 },
  { month: "2023-10", rate: 3.6 },
  { month: "2023-11", rate: 3.5 },
  { month: "2023-12", rate: 3.6 },
  { month: "2024-01", rate: 3.4 },
  { month: "2024-02", rate: 3.7 },
  { month: "2024-03", rate: 3.8 },
  { month: "2024-04", rate: 3.9 },
  { month: "2024-05", rate: 4.1 },
  { month: "2024-06", rate: 4.3 },
  { month: "2024-07", rate: 4.2 },
  { month: "2024-08", rate: 4.1 },
  { month: "2024-09", rate: 4.2 },
  { month: "2024-10", rate: 4.4 },
];

<Sparkline
  data={data}
  x="month"
  y="rate"
  format="{value}%"
  showValue
  extremes
  style={{ maxWidth: 220 }}
  alt="Sparkline of the unemployment rate over 16 months, July 2023 to October 2024. It started at 3.9%, fell to 3.4% in January 2024 and ended at 4.4%, the highest in the period."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "sparkline",
  "data": [
    { "month": "2023-07", "rate": 3.9 },
    { "month": "2023-08", "rate": 3.8 },
    { "month": "2023-09", "rate": 3.8 },
    { "month": "2023-10", "rate": 3.6 },
    { "month": "2023-11", "rate": 3.5 },
    { "month": "2023-12", "rate": 3.6 },
    { "month": "2024-01", "rate": 3.4 },
    { "month": "2024-02", "rate": 3.7 },
    { "month": "2024-03", "rate": 3.8 },
    { "month": "2024-04", "rate": 3.9 },
    { "month": "2024-05", "rate": 4.1 },
    { "month": "2024-06", "rate": 4.3 },
    { "month": "2024-07", "rate": 4.2 },
    { "month": "2024-08", "rate": 4.1 },
    { "month": "2024-09", "rate": 4.2 },
    { "month": "2024-10", "rate": 4.4 }
  ],
  "x": "month",
  "y": "rate",
  "format": "{value}%",
  "showValue": true,
  "extremes": true,
  "style": { "maxWidth": 220 },
  "alt": "Sparkline of the unemployment rate over 16 months, July 2023 to October 2024. It started at 3.9%, fell to 3.4% in January 2024 and ended at 4.4%, the highest in the period."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `y` (required) | `string` |  | Value field. |
| `x` | `string` |  | Time or label field, used in the tooltip and alt text. Rows are drawn in data order. |
| `mark` | `"line" \| "bar"` | `"line"` | Line for a trend, bars for discrete counts or gains and losses (negative bars take the negative colour). |
| `extremes` | `boolean` | `false` | Mark the lowest and highest points with small dots. |
| `band` | `[number, number]` |  | Shaded reference range in value units, e.g. a normal range. |
| `area` | `boolean` | `false` | Light fill under the line; forces a zero baseline. |
| `showValue` | `boolean` | `false` | Print the last value after the line. |
| `zero` | `boolean` |  | Include zero in the scale. Default: off for lines, always on for bars. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [annotated-timeline](https://insightcharts.dev/llms/annotated-timeline.md), [before-after](https://insightcharts.dev/llms/before-after.md), [comparison-table](https://insightcharts.dev/llms/comparison-table.md), [quote-figure](https://insightcharts.dev/llms/quote-figure.md), [trend-card](https://insightcharts.dev/llms/trend-card.md)

### More examples

#### With a reference band

```tsx
import { Sparkline } from "insightcharts";

const data = [
  { reading: 1, mmol: 5.6 },
  { reading: 2, mmol: 5.8 },
  { reading: 3, mmol: 5.5 },
  { reading: 4, mmol: 5.6 },
  { reading: 5, mmol: 5.2 },
  { reading: 6, mmol: 5.3 },
  { reading: 7, mmol: 5.5 },
  { reading: 8, mmol: 5.5 },
  // ... 40 more rows
];

<Sparkline
  data={data}
  x="reading"
  y="mmol"
  band={[3.9, 7]}
  extremes
  showValue
  format="decimal:1"
  style={{ maxWidth: 280 }}
  title="Blood glucose over 48 readings"
  subtitle="Blood glucose, mmol/L. The band is the 3.9 to 7.0 target range."
  note="Illustrative data"
/>
```

#### Bars: gains and losses

```tsx
import { Sparkline } from "insightcharts";

const data = [
  { week: "W1", net: 4 },
  { week: "W2", net: 7 },
  { week: "W3", net: -3 },
  { week: "W4", net: 5 },
  { week: "W5", net: 9 },
  { week: "W6", net: -6 },
  { week: "W7", net: -2 },
  { week: "W8", net: 8 },
  // ... 6 more rows
];

<Sparkline
  data={data}
  x="week"
  y="net"
  mark="bar"
  showValue
  format="signed"
  style={{ maxWidth: 220 }}
/>
```

#### Area fill, full width

```tsx
import { Sparkline } from "insightcharts";

const data = [
  { month: 1, signups: 18 },
  { month: 2, signups: 22 },
  { month: 3, signups: 21 },
  { month: 4, signups: 27 },
  { month: 5, signups: 33 },
  { month: 6, signups: 31 },
  { month: 7, signups: 38 },
  { month: 8, signups: 44 },
  // ... 4 more rows
];

<Sparkline data={data} y="signups" area height={56} />
```

#### Stress: 400 points in 160px

```tsx
import { Sparkline } from "insightcharts";

const data = [
  { day: 1, price: 99.86 },
  { day: 2, price: 99.76 },
  { day: 3, price: 99.17 },
  { day: 4, price: 98.87 },
  { day: 5, price: 98.87 },
  { day: 6, price: 100.1 },
  { day: 7, price: 101.27 },
  { day: 8, price: 100.87 },
  // ... 392 more rows
];

<Sparkline
  data={data}
  x="day"
  y="price"
  extremes
  showValue
  format="decimal:0"
  style={{ maxWidth: 160 }}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/sparkline.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/sparkline.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Stat circles (`stat-circles`)

> Shows a few related magnitudes as plain circles sized by area, each with its number set large and a short label.

- Component: `StatCircles` (import from `insightcharts`)
- Spec type: `"stat-circles"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

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

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).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/stat-circles
```

The file lands at `components/insightcharts/atoms/stat-circles.tsx`. `@insightcharts/stat-circles-demo` adds a ready-made example next to it.

### Usage

```tsx
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 },
];

<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"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "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"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Label field: the short text under or beside each circle. |
| `value` (required) | `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 props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md), [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md), [scale-poster](https://insightcharts.dev/llms/scale-poster.md)

### More examples

#### Nested, shaded by value

```tsx
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 },
];

<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"
/>
```

#### Steps, with icons, highlight and click to select

```tsx
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 },
];

<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"
/>
```

#### Stress: six circles, long labels, values from 2 to 9,800

```tsx
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 },
];

<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"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/stat-circles.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/stat-circles.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Stat tile (`stat-tile`)

> A compact, bordered KPI tile: label, value, change against a baseline and an optional trend graphic.

- Component: `StatTile` (import from `insightcharts`)
- Spec type: `"stat-tile"`
- Level: atom. Category: figure.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Dashboard grids and KPI rows of three to six figures, each needing its own change indicator or sparkline. Give every tile a delta or a context line.

### Avoid

The single number a story leads with (use `big-number` with `size: "hero"`). Do not put a full chart with axes in the trend slot.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/stat-tile
```

The file lands at `components/insightcharts/atoms/stat-tile.tsx`. `@insightcharts/stat-tile-demo` adds a ready-made example next to it.

### Usage

```tsx
import { StatTile } from "insightcharts";

<StatTile
  label="Monthly active users"
  value={48210}
  format="compact"
  delta={0.083}
  deltaLabel="vs September"
  trend={[38.1, 39.4, 39, 40.8, 42.2, 41.9, 43.5, 44.1, 44.5, 46, 47.2, 48.2]}
  style={{ maxWidth: 300 }}
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "stat-tile",
  "label": "Monthly active users",
  "value": 48210,
  "format": "compact",
  "delta": 0.083,
  "deltaLabel": "vs September",
  "trend": [38.1, 39.4, 39, 40.8, 42.2, 41.9, 43.5, 44.1, 44.5, 46, 47.2, 48.2],
  "style": { "maxWidth": 300 }
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` (required) | `string` |  | What it measures, sentence case. |
| `value` (required) | `number \| string` |  | The figure. Numbers are formatted with `format`. |
| `delta` | `number \| string` |  | Change against a baseline. Numbers render as signed percentages (0.12 is +12%). |
| `deltaLabel` | `string` |  | What the delta is against, e.g. "vs last month". |
| `upIsGood` | `boolean` | `true` | Whether an increase is an improvement. Sets the delta colour. |
| `context` | `string` |  | A line that states a comparison or reference for the number. |
| `trend` | `Slot \| number[]` |  | A chart spec, a React element, or an array of numbers drawn as a sparkline. |
| `trendPosition` | `"bottom" \| "right"` | `"bottom"` | Where the trend sits; `right` falls back to `bottom` under 280px. |
| `format` | `FormatSpec` | `"auto"` | Number format for `value`. |
| `children` | `ReactNode` |  | Extra content at the bottom of the tile. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [section](https://insightcharts.dev/llms/section.md), [stat-row](https://insightcharts.dev/llms/stat-row.md), [trend-card](https://insightcharts.dev/llms/trend-card.md)

### More examples

#### Down is good, trend on the right

```tsx
import { StatTile } from "insightcharts";

<StatTile
  label="Median first-response time"
  value="2 h 14 min"
  delta={-0.18}
  deltaLabel="vs last quarter"
  upIsGood={false}
  trend={[4.1, 3.9, 3.8, 3.2, 3.4, 2.9, 2.7, 2.4, 2.2]}
  trendPosition="right"
  style={{ maxWidth: 420 }}
/>
```

#### Context only

```tsx
import { StatTile } from "insightcharts";

<StatTile
  label="Net revenue retention"
  value={1.12}
  format="percent"
  context="Top quartile for the sector is 110%."
  style={{ maxWidth: 260 }}
/>
```

#### Chart spec in the trend slot

```tsx
import { BigNumber, StatTile } from "insightcharts";

<StatTile
  label="Solar share of generation"
  value={0.113}
  format="percent"
  delta="+1.9 pts"
  deltaLabel="vs 2023"
  trend={<BigNumber
    label="Peak hour, 14 July"
    value={0.52}
    format="percent"
    context="Any registered component can sit here."
  />}
  style={{ maxWidth: 300 }}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/stat-tile.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/stat-tile.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Step marker (`step-marker`)

> A numbered chapter or step heading ("01 — Electricity sources in 2015") for sequencing the sections of a story.

- Component: `StepMarker` (import from `insightcharts`)
- Spec type: `"step-marker"`
- Level: atom. Category: text.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

When a piece has three to seven ordered chapters or steps. Open each one with a marker so the reader can see the position in the sequence.

### Avoid

Unordered sections (use `headline` with `size: "section"`), or numbering a list of items inside a paragraph.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/step-marker
```

The file lands at `components/insightcharts/atoms/step-marker.tsx`. `@insightcharts/step-marker-demo` adds a ready-made example next to it.

### Usage

```tsx
import { StepMarker } from "insightcharts";

<StepMarker
  step={1}
  title="Electricity sources in 2015"
  text="Europe's electricity generation by source in 2015."
  size="lg"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "step-marker",
  "step": 1,
  "title": "Electricity sources in 2015",
  "text": "Europe's electricity generation by source in 2015.",
  "size": "lg"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `step` (required) | `number \| string` |  | Step number, zero-padded to two digits. Strings are shown as written. |
| `title` (required) | `string` |  | The chapter or step title. |
| `total` | `number` |  | Total steps; the marker then reads "02 / 05". |
| `text` | `string` |  | A sentence under the title. |
| `children` | `ReactNode` |  | JSX alternative to `text`. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading level. |
| `size` | `"md" \| "lg"` | `"md"` | `lg` for chapter openers. |
| `layout` | `"inline" \| "stacked"` | `"inline"` | Number beside or above the title. Narrow containers always stack. |
| `rule` | `boolean` | `false` | Hairline above the marker. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [annotated-timeline](https://insightcharts.dev/llms/annotated-timeline.md), [section](https://insightcharts.dev/llms/section.md), [explainer](https://insightcharts.dev/llms/explainer.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### With total and rule

```tsx
import { StepMarker } from "insightcharts";

<StepMarker
  step={2}
  total={5}
  title="Solar module costs fell 82% in eight years"
  text="Average module cost per watt in each year."
  rule
/>
```

#### Stacked

```tsx
import { StepMarker } from "insightcharts";

<StepMarker
  step={3}
  title="Hours in which midday solar generation exceeded demand on the grid, by month and country"
  layout="stacked"
  size="lg"
/>
```

#### Letter step, title only

```tsx
import { StepMarker } from "insightcharts";

<StepMarker step="B" title="Factors excluded from the forecast" level={3} />
```

### Links

- Registry item: https://insightcharts.dev/r/step-marker.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/step-marker.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Strip plot (`strip-plot`)

> Shows every observation as a tick or dot along a value axis, one row per category.

- Component: `StripPlot` (import from `insightcharts`)
- Spec type: `"strip-plot"`
- Level: atom. Category: distribution.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Comparing the spread and clustering of a numeric value across 2 to about 15 categories when there are few enough observations to show each one; many rows with few to a few hundred observations each.

### Avoid

A single group where the shape matters (use histogram or beeswarm-chart); when individual points must be identifiable or coloured (use beeswarm-chart); when only quartiles matter (use box-plot).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/strip-plot
```

The file lands at `components/insightcharts/atoms/strip-plot.tsx`. `@insightcharts/strip-plot-demo` adds a ready-made example next to it.

### Usage

```tsx
import { StripPlot } from "insightcharts";

const data = [
  { day: "Mon", minutes: 42 },
  { day: "Mon", minutes: 44 },
  { day: "Mon", minutes: 45 },
  { day: "Mon", minutes: 47 },
  { day: "Mon", minutes: 47 },
  { day: "Mon", minutes: 48 },
  { day: "Mon", minutes: 49 },
  { day: "Mon", minutes: 51 },
  { day: "Mon", minutes: 52 },
  { day: "Mon", minutes: 55 },
  { day: "Mon", minutes: 58 },
  { day: "Mon", minutes: 63 },
  { day: "Tue", minutes: 40 },
  { day: "Tue", minutes: 41 },
  { day: "Tue", minutes: 43 },
  { day: "Tue", minutes: 43 },
  { day: "Tue", minutes: 44 },
  { day: "Tue", minutes: 45 },
  { day: "Tue", minutes: 46 },
  { day: "Tue", minutes: 46 },
  { day: "Tue", minutes: 48 },
  { day: "Tue", minutes: 49 },
  { day: "Tue", minutes: 53 },
  { day: "Tue", minutes: 57 },
  { day: "Wed", minutes: 39 },
  { day: "Wed", minutes: 41 },
  { day: "Wed", minutes: 42 },
  { day: "Wed", minutes: 44 },
  { day: "Wed", minutes: 44 },
  { day: "Wed", minutes: 45 },
  { day: "Wed", minutes: 45 },
  { day: "Wed", minutes: 47 },
  { day: "Wed", minutes: 48 },
  { day: "Wed", minutes: 50 },
  { day: "Wed", minutes: 52 },
  { day: "Wed", minutes: 61 },
  { day: "Thu", minutes: 41 },
  { day: "Thu", minutes: 43 },
  { day: "Thu", minutes: 44 },
  { day: "Thu", minutes: 46 },
  { day: "Thu", minutes: 47 },
  { day: "Thu", minutes: 47 },
  { day: "Thu", minutes: 49 },
  { day: "Thu", minutes: 50 },
  { day: "Thu", minutes: 52 },
  { day: "Thu", minutes: 54 },
  { day: "Thu", minutes: 59 },
  { day: "Thu", minutes: 66 },
  { day: "Fri", minutes: 36 },
  { day: "Fri", minutes: 37 },
  { day: "Fri", minutes: 38 },
  { day: "Fri", minutes: 39 },
  { day: "Fri", minutes: 40 },
  { day: "Fri", minutes: 40 },
  { day: "Fri", minutes: 41 },
  { day: "Fri", minutes: 42 },
  { day: "Fri", minutes: 43 },
  { day: "Fri", minutes: 44 },
  { day: "Fri", minutes: 46 },
  { day: "Fri", minutes: 49 },
];

<StripPlot
  data={data}
  value="minutes"
  group="day"
  median
  highlight="Fri"
  format="{value} min"
  title="The median Friday commute took 40.5 minutes"
  subtitle="Door-to-door commute time, 12 weeks of trips by weekday. The heavy tick is the median."
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "strip-plot",
  "data": [
    { "day": "Mon", "minutes": 42 },
    { "day": "Mon", "minutes": 44 },
    { "day": "Mon", "minutes": 45 },
    { "day": "Mon", "minutes": 47 },
    { "day": "Mon", "minutes": 47 },
    { "day": "Mon", "minutes": 48 },
    { "day": "Mon", "minutes": 49 },
    { "day": "Mon", "minutes": 51 },
    { "day": "Mon", "minutes": 52 },
    { "day": "Mon", "minutes": 55 },
    { "day": "Mon", "minutes": 58 },
    { "day": "Mon", "minutes": 63 },
    { "day": "Tue", "minutes": 40 },
    { "day": "Tue", "minutes": 41 },
    { "day": "Tue", "minutes": 43 },
    { "day": "Tue", "minutes": 43 },
    { "day": "Tue", "minutes": 44 },
    { "day": "Tue", "minutes": 45 },
    { "day": "Tue", "minutes": 46 },
    { "day": "Tue", "minutes": 46 },
    { "day": "Tue", "minutes": 48 },
    { "day": "Tue", "minutes": 49 },
    { "day": "Tue", "minutes": 53 },
    { "day": "Tue", "minutes": 57 },
    { "day": "Wed", "minutes": 39 },
    { "day": "Wed", "minutes": 41 },
    { "day": "Wed", "minutes": 42 },
    { "day": "Wed", "minutes": 44 },
    { "day": "Wed", "minutes": 44 },
    { "day": "Wed", "minutes": 45 },
    { "day": "Wed", "minutes": 45 },
    { "day": "Wed", "minutes": 47 },
    { "day": "Wed", "minutes": 48 },
    { "day": "Wed", "minutes": 50 },
    { "day": "Wed", "minutes": 52 },
    { "day": "Wed", "minutes": 61 },
    { "day": "Thu", "minutes": 41 },
    { "day": "Thu", "minutes": 43 },
    { "day": "Thu", "minutes": 44 },
    { "day": "Thu", "minutes": 46 },
    { "day": "Thu", "minutes": 47 },
    { "day": "Thu", "minutes": 47 },
    { "day": "Thu", "minutes": 49 },
    { "day": "Thu", "minutes": 50 },
    { "day": "Thu", "minutes": 52 },
    { "day": "Thu", "minutes": 54 },
    { "day": "Thu", "minutes": 59 },
    { "day": "Thu", "minutes": 66 },
    { "day": "Fri", "minutes": 36 },
    { "day": "Fri", "minutes": 37 },
    { "day": "Fri", "minutes": 38 },
    { "day": "Fri", "minutes": 39 },
    { "day": "Fri", "minutes": 40 },
    { "day": "Fri", "minutes": 40 },
    { "day": "Fri", "minutes": 41 },
    { "day": "Fri", "minutes": 42 },
    { "day": "Fri", "minutes": 43 },
    { "day": "Fri", "minutes": 44 },
    { "day": "Fri", "minutes": 46 },
    { "day": "Fri", "minutes": 49 }
  ],
  "value": "minutes",
  "group": "day",
  "median": true,
  "highlight": "Fri",
  "format": "{value} min",
  "title": "The median Friday commute took 40.5 minutes",
  "subtitle": "Door-to-door commute time, 12 weeks of trips by weekday. The heavy tick is the median.",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `string` |  | Numeric field positioning each mark. |
| `group` (required) | `string` |  | Category field: one row per distinct value. |
| `label` | `string` |  | Field naming each observation, for the tooltip. |
| `mark` | `"tick" \| "dot"` | `"tick"` | Thin vertical ticks (a barcode) or translucent dots. |
| `median` | `boolean` | `false` | Heavier tick at each row's median, with its value printed. |
| `sort` | `"none" \| "asc" \| "desc"` | `"none"` | Order rows by median. |
| `jitter` | `boolean` | `false` | Deterministic vertical spread for dots, to relieve overplotting. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: no molecule or template yet

### More examples

#### Barcode: 1,120 listings, sorted by median

```tsx
import { StripPlot } from "insightcharts";

const data = [
  { listing: "San Francisco #1", city: "San Francisco", rent: 2790 },
  { listing: "San Francisco #2", city: "San Francisco", rent: 3630 },
  { listing: "San Francisco #3", city: "San Francisco", rent: 2760 },
  { listing: "San Francisco #4", city: "San Francisco", rent: 3350 },
  { listing: "San Francisco #5", city: "San Francisco", rent: 2950 },
  { listing: "San Francisco #6", city: "San Francisco", rent: 2690 },
  { listing: "San Francisco #7", city: "San Francisco", rent: 2480 },
  { listing: "San Francisco #8", city: "San Francisco", rent: 3750 },
  // ... 1112 more rows
];

<StripPlot
  data={data}
  value="rent"
  group="city"
  label="listing"
  median
  sort="desc"
  format="currency:USD"
  height={400}
  title="Monthly rent of one-bedroom listings in 8 US cities"
  subtitle="US$ per month, 140 listings per city. The heavy tick is the median."
  note="Illustrative data"
/>
```

#### Dots with jitter, long labels

```tsx
import { StripPlot } from "insightcharts";

const data = [
  { pupil: "Pupil 1", school: "Northside Academy for Science and Technology", score: 67 },
  { pupil: "Pupil 2", school: "Northside Academy for Science and Technology", score: 44 },
  { pupil: "Pupil 3", school: "Northside Academy for Science and Technology", score: 60 },
  { pupil: "Pupil 4", school: "Northside Academy for Science and Technology", score: 62 },
  { pupil: "Pupil 5", school: "Northside Academy for Science and Technology", score: 59 },
  { pupil: "Pupil 6", school: "Northside Academy for Science and Technology", score: 41 },
  { pupil: "Pupil 7", school: "Northside Academy for Science and Technology", score: 54 },
  { pupil: "Pupil 8", school: "Northside Academy for Science and Technology", score: 67 },
  // ... 160 more rows
];

<StripPlot
  data={data}
  value="score"
  group="school"
  label="pupil"
  mark="dot"
  jitter
  median
  highlight="Westbrook"
  title="Exam scores at 6 schools"
  subtitle="Exam scores out of 100, 28 pupils per school"
  note="Illustrative data"
/>
```

#### Stress: 20 rows

```tsx
import { StripPlot } from "insightcharts";

const data = [
  { team: "Team A", days: 3.8 },
  { team: "Team A", days: 2.5 },
  { team: "Team A", days: 2.7 },
  { team: "Team A", days: 1.3 },
  { team: "Team A", days: 3.9 },
  { team: "Team A", days: 3.1 },
  { team: "Team A", days: 8 },
  { team: "Team A", days: 2.7 },
  // ... 792 more rows
];

<StripPlot
  data={data}
  value="days"
  group="team"
  format="{value}d"
  height={520}
  title="Days to close a ticket, 20 teams"
  subtitle="Days to close, 40 tickets per team"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/strip-plot.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/strip-plot.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Timeline chart (`timeline-chart`)

> Places events and spans on a time axis in labelled lanes, with each item named directly.

- Component: `TimelineChart` (import from `insightcharts`)
- Spec type: `"timeline-chart"`
- Level: atom. Category: trend.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

When things happened and how long they lasted: project phases, terms of office, product launches, the sequence of events in a story. Mix spans (start and end) with point milestones (start only).

### Avoid

A measured value changing over time (use line-chart, with annotations for the events); more than about 40 items (filter, or split into several timelines); durations to be compared precisely with no interest in when (use bar-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/timeline-chart
```

The file lands at `components/insightcharts/atoms/timeline-chart.tsx`. `@insightcharts/timeline-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { TimelineChart } from "insightcharts";

const data = [
  { mission: "Mercury", programme: "Crewed programmes", from: "1958-10", to: "1963-05" },
  { mission: "Gemini", programme: "Crewed programmes", from: "1961-12", to: "1966-11" },
  { mission: "Apollo", programme: "Crewed programmes", from: "1961-05", to: "1972-12" },
  { mission: "Skylab", programme: "Crewed programmes", from: "1973-05", to: "1974-02" },
  { mission: "Shuttle development", programme: "Crewed programmes", from: "1972-01", to: "1981-04" },
  { mission: "Glenn orbits Earth", programme: "Milestones", from: "1962-02-20" },
  { mission: "Apollo 1 fire", programme: "Milestones", from: "1967-01-27" },
  { mission: "First Moon landing", programme: "Milestones", from: "1969-07-20" },
  { mission: "Apollo-Soyuz", programme: "Milestones", from: "1975-07-15" },
  { mission: "First Shuttle flight", programme: "Milestones", from: "1981-04-12" },
];

<TimelineChart
  data={data}
  name="mission"
  start="from"
  end="to"
  lane="programme"
  highlight={["Apollo", "First Moon landing"]}
  title="The Apollo programme ran from May 1961 to December 1972"
  subtitle="NASA human spaceflight programmes and milestones, 1958 to 1981"
  source="NASA History Office"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "timeline-chart",
  "data": [
    { "mission": "Mercury", "programme": "Crewed programmes", "from": "1958-10", "to": "1963-05" },
    { "mission": "Gemini", "programme": "Crewed programmes", "from": "1961-12", "to": "1966-11" },
    { "mission": "Apollo", "programme": "Crewed programmes", "from": "1961-05", "to": "1972-12" },
    { "mission": "Skylab", "programme": "Crewed programmes", "from": "1973-05", "to": "1974-02" },
    {
      "mission": "Shuttle development",
      "programme": "Crewed programmes",
      "from": "1972-01",
      "to": "1981-04"
    },
    { "mission": "Glenn orbits Earth", "programme": "Milestones", "from": "1962-02-20" },
    { "mission": "Apollo 1 fire", "programme": "Milestones", "from": "1967-01-27" },
    { "mission": "First Moon landing", "programme": "Milestones", "from": "1969-07-20" },
    { "mission": "Apollo-Soyuz", "programme": "Milestones", "from": "1975-07-15" },
    { "mission": "First Shuttle flight", "programme": "Milestones", "from": "1981-04-12" }
  ],
  "name": "mission",
  "start": "from",
  "end": "to",
  "lane": "programme",
  "highlight": ["Apollo", "First Moon landing"],
  "title": "The Apollo programme ran from May 1961 to December 1972",
  "subtitle": "NASA human spaceflight programmes and milestones, 1958 to 1981",
  "source": "NASA History Office",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Label field: what the event or span is. |
| `start` (required) | `string` |  | Start field: ISO date, year or timestamp. |
| `end` | `string` |  | End field. Rows without an end are point milestones. |
| `lane` | `string` |  | Field that groups rows into labelled lanes. |
| `precision` | `"year" \| "month" \| "day"` |  | Date precision in tooltips. Default: chosen from the span of the data. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [timeline-story](https://insightcharts.dev/llms/timeline-story.md)

### More examples

#### Single lane, milestones only

```tsx
import { TimelineChart } from "insightcharts";

const data = [
  { event: "WHO told of pneumonia cluster", date: "2019-12-31" },
  { event: "Virus genome published", date: "2020-01-11" },
  { event: "Pandemic declared", date: "2020-03-11" },
  { event: "First vaccine trial results", date: "2020-11-09" },
  { event: "First approved dose given", date: "2020-12-08" },
];

<TimelineChart
  data={data}
  name="event"
  start="date"
  height={200}
  highlight="First approved dose given"
  title="The first approved Covid-19 vaccine dose was given on 8 December 2020"
  subtitle="Key dates in the first year of Covid-19, December 2019 to December 2020"
  source="WHO, MHRA"
  note="Figures are approximate, for illustration"
/>
```

#### Project plan with lanes

```tsx
import { TimelineChart } from "insightcharts";

const data = [
  { task: "Discovery", team: "Design", start: "2025-01-06", end: "2025-02-14" },
  { task: "Prototype", team: "Design", start: "2025-02-10", end: "2025-04-04" },
  { task: "Design system", team: "Design", start: "2025-03-17", end: "2025-06-27" },
  { task: "API", team: "Engineering", start: "2025-02-24", end: "2025-05-30" },
  { task: "Web app", team: "Engineering", start: "2025-04-07", end: "2025-08-15" },
  { task: "Beta", team: "Engineering", start: "2025-07-01" },
  { task: "Hardening", team: "Engineering", start: "2025-08-04", end: "2025-09-19" },
  { task: "Pricing research", team: "Go to market", start: "2025-03-03", end: "2025-04-25" },
  // ... 2 more rows
];

<TimelineChart
  data={data}
  name="task"
  start="start"
  end="end"
  lane="team"
  title="Public launch is planned for 23 September 2025"
  subtitle="Product roadmap by team, 2025"
  note="Illustrative plan"
/>
```

#### Stress: long names, crowded lanes, centuries

```tsx
import { TimelineChart } from "insightcharts";

const data = [
  { who: "Elizabeth I", house: "Tudor", from: 1558, to: 1603 },
  { who: "James VI and I", house: "Stuart", from: 1603, to: 1625 },
  { who: "Charles I", house: "Stuart", from: 1625, to: 1649 },
  { who: "Commonwealth and Protectorate", house: "Interregnum", from: 1649, to: 1660 },
  { who: "Charles II", house: "Stuart", from: 1660, to: 1685 },
  { who: "James II", house: "Stuart", from: 1685, to: 1688 },
  { who: "William III and Mary II", house: "Stuart", from: 1689, to: 1702 },
  { who: "Anne", house: "Stuart", from: 1702, to: 1714 },
  // ... 13 more rows
];

<TimelineChart
  data={data}
  name="who"
  start="from"
  end="to"
  lane="house"
  height={420}
  title="Victoria reigned from 1837 to 1901"
  subtitle="English and British monarchs by royal house, 1558 to 1901"
  source="Royal Household"
  note="Figures are approximate, for illustration"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/timeline-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/timeline-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Treemap (`treemap`)

> Shows parts of a whole as nested rectangles sized by value, optionally grouped into categories.

- Component: `Treemap` (import from `insightcharts`)
- Spec type: `"treemap"`
- Level: atom. Category: part-to-whole.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Many parts (10 to 100) of very different sizes, or a two-level hierarchy, where the reader needs the largest parts rather than exact comparison: budgets, market capitalisation, export baskets.

### Avoid

Fewer than about 6 parts or values that need precise comparison (use bar-chart); 2 to 5 parts (use donut-chart or segmented-bar); values that can be negative (use bar-chart); change over time (use line-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/treemap
```

The file lands at `components/insightcharts/atoms/treemap.tsx`. `@insightcharts/treemap-demo` adds a ready-made example next to it.

### Usage

```tsx
import { Treemap } from "insightcharts";

const data = [
  { sector: "Energy", source: "Electricity and heat", gt: 15.8 },
  { sector: "Energy", source: "Transport", gt: 8.4 },
  { sector: "Energy", source: "Manufacturing and construction", gt: 6.3 },
  { sector: "Energy", source: "Buildings", gt: 3 },
  { sector: "Energy", source: "Fugitive emissions", gt: 3.3 },
  { sector: "Agriculture", source: "Livestock and manure", gt: 3.5 },
  { sector: "Agriculture", source: "Soils and rice", gt: 2.4 },
  { sector: "Industry", source: "Cement", gt: 1.6 },
  { sector: "Industry", source: "Chemicals and other", gt: 1.6 },
  { sector: "Waste", source: "Landfill and wastewater", gt: 1.7 },
  { sector: "Land use", source: "Deforestation and land-use change", gt: 1.4 },
];

<Treemap
  data={data}
  group="sector"
  name="source"
  value="gt"
  format="{value} Gt"
  title="Energy produced 75% of global greenhouse gas emissions in 2021"
  subtitle="Global emissions by sector and source, billion tonnes of CO2 equivalent, 2021"
  source="Climate Watch, World Resources Institute"
  note="Rounded, approximate figures for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "treemap",
  "data": [
    { "sector": "Energy", "source": "Electricity and heat", "gt": 15.8 },
    { "sector": "Energy", "source": "Transport", "gt": 8.4 },
    { "sector": "Energy", "source": "Manufacturing and construction", "gt": 6.3 },
    { "sector": "Energy", "source": "Buildings", "gt": 3 },
    { "sector": "Energy", "source": "Fugitive emissions", "gt": 3.3 },
    { "sector": "Agriculture", "source": "Livestock and manure", "gt": 3.5 },
    { "sector": "Agriculture", "source": "Soils and rice", "gt": 2.4 },
    { "sector": "Industry", "source": "Cement", "gt": 1.6 },
    { "sector": "Industry", "source": "Chemicals and other", "gt": 1.6 },
    { "sector": "Waste", "source": "Landfill and wastewater", "gt": 1.7 },
    { "sector": "Land use", "source": "Deforestation and land-use change", "gt": 1.4 }
  ],
  "group": "sector",
  "name": "source",
  "value": "gt",
  "format": "{value} Gt",
  "title": "Energy produced 75% of global greenhouse gas emissions in 2021",
  "subtitle": "Global emissions by sector and source, billion tonnes of CO2 equivalent, 2021",
  "source": "Climate Watch, World Resources Institute",
  "note": "Rounded, approximate figures for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Leaf name field: one tile per row. |
| `value` (required) | `string` |  | Value field: tile area. Non-positive values are dropped. |
| `group` | `string` |  | Parent field. Rows sharing a group are drawn together and share a colour. |
| `labels` | `boolean` | `true` | Print the value under the name where the tile is big enough. |
| `groupLabels` | `boolean` |  | Heading strip above each group. Default: on when `group` is set and not compact. |
| `names` | `Record<string, string>` |  | Display names for group keys. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [poster](https://insightcharts.dev/llms/poster.md), [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md), [flow-poster](https://insightcharts.dev/llms/flow-poster.md), [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md)

### More examples

#### Flat, with highlight

```tsx
import { Treemap } from "insightcharts";

const data = [
  { company: "Nvidia", cap: 3.3 },
  { company: "Apple", cap: 3.4 },
  { company: "Microsoft", cap: 3.1 },
  { company: "Alphabet", cap: 2.1 },
  { company: "Amazon", cap: 2 },
  { company: "Meta", cap: 1.5 },
  { company: "Tesla", cap: 0.8 },
  { company: "Broadcom", cap: 0.8 },
  // ... 7 more rows
];

<Treemap
  data={data}
  name="company"
  value="cap"
  format="${value}tn"
  highlight={["Nvidia", "Apple", "Microsoft"]}
  title="Apple, Nvidia and Microsoft were worth $9.8 trillion combined in late 2024"
  subtitle="Market capitalisation of the 15 largest US-listed companies, late 2024, $ trillion"
  source="Company filings, exchange data"
  note="Rounded, illustrative"
/>
```

#### Stress: many small tiles and long names

```tsx
import { Treemap } from "insightcharts";

const data = [
  { area: "Health", programme: "Hospital and community health services", bn: 168 },
  { area: "Health", programme: "Primary care and prescribing", bn: 38 },
  { area: "Health", programme: "Public health grants to local authorities", bn: 4 },
  { area: "Social protection", programme: "State pension", bn: 124 },
  { area: "Social protection", programme: "Universal credit and legacy benefits", bn: 88 },
  { area: "Social protection", programme: "Disability and incapacity benefits", bn: 66 },
  { area: "Social protection", programme: "Housing benefit", bn: 16 },
  { area: "Social protection", programme: "Child benefit", bn: 12 },
  // ... 14 more rows
];

<Treemap
  data={data}
  group="area"
  name="programme"
  value="bn"
  format="£{value}bn"
  height={460}
  title="Social protection was £306bn of £910bn in UK public spending in 2023-24"
  subtitle="Public spending by area and programme, £ billion, 2023-24"
  source="HM Treasury Public Expenditure Statistical Analyses"
  note="Programme split is illustrative"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/treemap.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/treemap.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Unit blocks (`unit-blocks`)

> Shows the size of each group as a solid block of small icons, one icon per fixed number of units.

- Component: `UnitBlocks` (import from `insightcharts`)
- Spec type: `"unit-blocks"`
- Level: atom. Category: poster.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

Large counts of people or things in 2 to 12 groups, where the reader should see the crowd itself: 20,350 marathon finishers by age group, one figure per 10 runners.

### Avoid

Precise comparison of close values (use block-bar or bar-chart); fewer than about 30 icons per group (use pictogram-chart or icon-array-grid); shares of one whole (use waffle-chart).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/unit-blocks
```

The file lands at `components/insightcharts/atoms/unit-blocks.tsx`. `@insightcharts/unit-blocks-demo` adds a ready-made example next to it.

### Usage

```tsx
import { UnitBlocks } from "insightcharts";

const data = [
  { age: "Under 30", finishers: 4180 },
  { age: "30 to 39", finishers: 6920 },
  { age: "40 to 49", finishers: 5340 },
  { age: "50 to 59", finishers: 2760 },
  { age: "60 and over", finishers: 1150 },
];

<UnitBlocks
  data={data}
  name="age"
  value="finishers"
  unit={10}
  unitLabel="10 finishers"
  format="integer"
  title="6,920 of the 20,350 finishers were aged 30 to 39"
  subtitle="Finishers of the Lakeshore Marathon by age group, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional race"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "unit-blocks",
  "data": [
    { "age": "Under 30", "finishers": 4180 },
    { "age": "30 to 39", "finishers": 6920 },
    { "age": "40 to 49", "finishers": 5340 },
    { "age": "50 to 59", "finishers": 2760 },
    { "age": "60 and over", "finishers": 1150 }
  ],
  "name": "age",
  "value": "finishers",
  "unit": 10,
  "unitLabel": "10 finishers",
  "format": "integer",
  "title": "6,920 of the 20,350 finishers were aged 30 to 39",
  "subtitle": "Finishers of the Lakeshore Marathon by age group, 2025",
  "source": "Illustrative data",
  "note": "Invented figures for a fictional race"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` (required) | `string` |  | Group field: one block of icons per row of data. |
| `value` (required) | `string` |  | Value field: the quantity each block counts out. |
| `unit` | `number` |  | Units per icon. Default: a round number that gives about 2,000 icons in total. |
| `unitLabel` | `string` |  | What one icon stands for, for the key line, e.g. "10 finishers". |
| `icon` | `IconName \| "path://..."` | `"person"` | Built-in icon name or a custom single SVG path. |
| `series` | `string` |  | Field that colours the blocks. Default: one colour per group, up to eight groups. |
| `layout` | `"packed" \| "columns"` | `"packed"` | `packed`: equal block heights, widths follow the counts. `columns`: equal widths, blocks grow upwards from a baseline. |
| `columns` | `number` |  | Blocks per line in the `columns` layout. Default: all, two on a phone. |
| `iconSize` | `number` |  | Icon height in px. Default: the largest that fits, chosen per chart. To put two charts on one scale, give both the same `unit` and `iconSize`: the icon size, the gaps and the worth of an icon are then identical and the chart takes the height it needs. |
| `sort` | `"none" \| "asc" \| "desc"` | `"none"` | Order of the blocks. |

### Common props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [count-poster](https://insightcharts.dev/llms/count-poster.md)

### More examples

#### Highlight, click to select

```tsx
import { UnitBlocks } from "insightcharts";

const data = [
  { age: "Under 30", finishers: 4180 },
  { age: "30 to 39", finishers: 6920 },
  { age: "40 to 49", finishers: 5340 },
  { age: "50 to 59", finishers: 2760 },
  { age: "60 and over", finishers: 1150 },
];

<UnitBlocks
  data={data}
  name="age"
  value="finishers"
  unit={10}
  unitLabel="10 finishers"
  format="integer"
  highlight="60 and over"
  select
  title="1,150 finishers were aged 60 or over"
  subtitle="Finishers of the Lakeshore Marathon by age group, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional race"
/>
```

#### Stress: 20,350 icons, one per finisher

```tsx
import { UnitBlocks } from "insightcharts";

const data = [
  { age: "Under 30", finishers: 4180 },
  { age: "30 to 39", finishers: 6920 },
  { age: "40 to 49", finishers: 5340 },
  { age: "50 to 59", finishers: 2760 },
  { age: "60 and over", finishers: 1150 },
];

<UnitBlocks
  data={data}
  name="age"
  value="finishers"
  unit={1}
  unitLabel="1 finisher"
  format="integer"
  title="20,350 people finished the Lakeshore Marathon in 2025"
  subtitle="Finishers by age group. Every figure is one runner"
  source="Illustrative data"
  note="Invented figures for a fictional race"
/>
```

#### Columns of squares, coloured by a series field

```tsx
import { UnitBlocks } from "insightcharts";

const data = [
  { depot: "Northgate", buses: 412, fuel: "Electric" },
  { depot: "Harbour Road", buses: 268, fuel: "Electric" },
  { depot: "Millbrook", buses: 655, fuel: "Diesel" },
  { depot: "Eastfield", buses: 381, fuel: "Diesel" },
  { depot: "Quarry Lane", buses: 97, fuel: "Hydrogen" },
];

<UnitBlocks
  data={data}
  name="depot"
  value="buses"
  series="fuel"
  unit={1}
  unitLabel="1 bus"
  icon="square"
  layout="columns"
  title="Millbrook depot ran 655 diesel buses in 2025"
  subtitle="Buses in service by depot and fuel, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional operator"
/>
```

#### Stress: twelve uneven groups, long names

```tsx
import { UnitBlocks } from "insightcharts";

const data = [
  { species: "Common starling", birds: 9840 },
  { species: "House sparrow", birds: 7120 },
  { species: "Wood pigeon", birds: 5310 },
  { species: "Blackbird", birds: 3980 },
  { species: "Blue tit", birds: 3460 },
  { species: "European goldfinch", birds: 2210 },
  { species: "Great spotted woodpecker", birds: 640 },
  { species: "Long-tailed tit", birds: 580 },
  // ... 4 more rows
];

<UnitBlocks
  data={data}
  name="species"
  value="birds"
  unit={20}
  unitLabel="20 birds"
  icon="circle"
  format="integer"
  title="Volunteers counted 9,840 starlings in one weekend in 2025"
  subtitle="Birds recorded in one weekend garden count by species, 2025"
  source="Illustrative data"
  note="Invented figures for a fictional survey"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/unit-blocks.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/unit-blocks.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Waffle chart (`waffle-chart`)

> Shows shares of a whole as counted cells in a grid, such as 37 in every 100.

- Component: `WaffleChart` (import from `insightcharts`)
- Spec type: `"waffle-chart"`
- Level: atom. Category: part-to-whole.
- An ECharts chart built with `defineChart`: accepts every common chart prop (data, transform, title, highlight, annotations, ...).

### When to use

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

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).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/waffle-chart
```

The file lands at `components/insightcharts/atoms/waffle-chart.tsx`. `@insightcharts/waffle-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { WaffleChart } from "insightcharts";

<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"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "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"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `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 props

Also accepts every prop in the "Common chart props" section of this file.

### Composition

- Composes: nothing (it is a primitive)
- Used by: [poster](https://insightcharts.dev/llms/poster.md), [proportion-statement](https://insightcharts.dev/llms/proportion-statement.md), [small-multiple-grid](https://insightcharts.dev/llms/small-multiple-grid.md), [social-card](https://insightcharts.dev/llms/social-card.md)

### More examples

#### Several categories

```tsx
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 },
];

<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"
/>
```

#### Highlight, circles

```tsx
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 },
];

<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"
/>
```

#### Stress: long names, wide grid, rounding

```tsx
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 },
];

<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"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/waffle-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/atoms/waffle-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Annotated timeline (`annotated-timeline`)

> A vertical sequence of dated events along a rail, each with a short explanation and, optionally, a small chart or figure.

- Component: `AnnotatedTimeline` (import from `insightcharts`)
- Spec type: `"annotated-timeline"`
- Level: molecule. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Telling how something unfolded when the events matter more than a continuous measure: a policy history, an incident, a product's milestones. Four to eight events; give a figure only to the ones where a number changed.

### Avoid

Events that should be read against a time scale, with gaps and overlaps to scale (use `timeline-chart`); a continuous series with a few annotated moments (use `line-chart` with `annotations`); ordered steps that are not dated (use `section` with `step`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/annotated-timeline
```

The file lands at `components/insightcharts/molecules/annotated-timeline.tsx`. `@insightcharts/annotated-timeline-demo` adds a ready-made example next to it.

### Usage

```tsx
import { AnnotatedTimeline, BigNumber, Sparkline } from "insightcharts";

<AnnotatedTimeline
  title="The ECB raised its deposit rate from −0.5% to 4% between July 2022 and September 2023"
  subtitle="Euro area deposit facility rate and annual inflation, 2021 to 2024"
  events={[
    {
      date: "July 2021",
      title: "Inflation reaches 2.2%",
      text: "The ECB's target is 2%. The bank kept its deposit rate at −0.5%.",
    },
    {
      date: "July 2022",
      title: "The deposit rate rises from −0.5% to 0%",
      emphasis: true,
      text: "This was the ECB's first rate rise in eleven years. Inflation was 8.9%.",
      figure: <BigNumber value="8.9%" label="Annual inflation, July 2022" context="The target is 2%" />,
    },
    {
      date: "October 2022",
      title: "Inflation reaches 10.6%",
      text: "This was the highest monthly figure of 2022. The ECB raised rates by 0.75 points at each of two consecutive meetings.",
      figure: <Sparkline
        data={[
          { month: "2022-01", rate: 5.1 },
          { month: "2022-02", rate: 5.9 },
          { month: "2022-03", rate: 7.4 },
          { month: "2022-04", rate: 7.4 },
          { month: "2022-05", rate: 8.1 },
          { month: "2022-06", rate: 8.6 },
          { month: "2022-07", rate: 8.9 },
          { month: "2022-08", rate: 9.1 },
          { month: "2022-09", rate: 9.9 },
          { month: "2022-10", rate: 10.6 },
          { month: "2022-11", rate: 10.1 },
          { month: "2022-12", rate: 9.2 },
        ]}
        x="month"
        y="rate"
        format="{value}%"
        extremes
        showValue
        style={{ maxWidth: 260 }}
      />,
    },
    {
      date: "September 2023",
      title: "The deposit rate reaches 4%",
      text: "This was the tenth rise in a row. Inflation was 4.3%.",
    },
    {
      date: "June 2024",
      title: "The deposit rate is cut to 3.75%",
      emphasis: true,
      text: "The cut was 0.25 points. Inflation was 2.5%.",
    },
  ]}
  source="European Central Bank; Eurostat"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "annotated-timeline",
  "title": "The ECB raised its deposit rate from −0.5% to 4% between July 2022 and September 2023",
  "subtitle": "Euro area deposit facility rate and annual inflation, 2021 to 2024",
  "events": [
    {
      "date": "July 2021",
      "title": "Inflation reaches 2.2%",
      "text": "The ECB's target is 2%. The bank kept its deposit rate at −0.5%."
    },
    {
      "date": "July 2022",
      "title": "The deposit rate rises from −0.5% to 0%",
      "emphasis": true,
      "text": "This was the ECB's first rate rise in eleven years. Inflation was 8.9%.",
      "figure": {
        "type": "big-number",
        "value": "8.9%",
        "label": "Annual inflation, July 2022",
        "context": "The target is 2%"
      }
    },
    {
      "date": "October 2022",
      "title": "Inflation reaches 10.6%",
      "text": "This was the highest monthly figure of 2022. The ECB raised rates by 0.75 points at each of two consecutive meetings.",
      "figure": {
        "type": "sparkline",
        "data": [
          { "month": "2022-01", "rate": 5.1 },
          { "month": "2022-02", "rate": 5.9 },
          { "month": "2022-03", "rate": 7.4 },
          { "month": "2022-04", "rate": 7.4 },
          { "month": "2022-05", "rate": 8.1 },
          { "month": "2022-06", "rate": 8.6 },
          { "month": "2022-07", "rate": 8.9 },
          { "month": "2022-08", "rate": 9.1 },
          { "month": "2022-09", "rate": 9.9 },
          { "month": "2022-10", "rate": 10.6 },
          { "month": "2022-11", "rate": 10.1 },
          { "month": "2022-12", "rate": 9.2 }
        ],
        "x": "month",
        "y": "rate",
        "format": "{value}%",
        "extremes": true,
        "showValue": true,
        "style": { "maxWidth": 260 }
      }
    },
    {
      "date": "September 2023",
      "title": "The deposit rate reaches 4%",
      "text": "This was the tenth rise in a row. Inflation was 4.3%."
    },
    {
      "date": "June 2024",
      "title": "The deposit rate is cut to 3.75%",
      "emphasis": true,
      "text": "The cut was 0.25 points. Inflation was 2.5%."
    }
  ],
  "source": "European Central Bank; Eurostat",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `events` (required) | `{ date, title, text?, figure?, emphasis? }[]` |  | The events in reading order. `date` is shown as written; `figure` is a chart spec or element; `emphasis` fills the marker to mark the most important events. |
| `figurePosition` | `"below" \| "side"` | `"below"` | Where an event's figure sits; `side` falls back to `below` under 640px. |
| `level` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | Heading level of the event titles. |
| `title` | `string` |  | The main fact with its number, or a plain label. |
| `subtitle` | `string` |  | Scope and period. |
| `source` | `string` |  | Shown under the timeline as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to every event. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [step-marker](https://insightcharts.dev/llms/step-marker.md), [prose](https://insightcharts.dev/llms/prose.md), [sparkline](https://insightcharts.dev/llms/sparkline.md), [big-number](https://insightcharts.dev/llms/big-number.md)
- Used by: [timeline-story](https://insightcharts.dev/llms/timeline-story.md)

### More examples

#### Figures at the side

```tsx
import { AnnotatedTimeline, BigNumber } from "insightcharts";

<AnnotatedTimeline
  figurePosition="side"
  events={[
    {
      date: "2015",
      title: "The Paris Agreement is signed",
      text: "Solar supplied 2.9% of EU electricity. Coal supplied 24.6%.",
      figure: <BigNumber value="2.9%" label="Solar share of EU electricity" />,
    },
    {
      date: "2019",
      title: "Solar module prices are half their 2015 level",
      text: "New utility-scale solar costs less than new gas plants in southern Europe.",
    },
    {
      date: "2022",
      title: "The EU adds 41 GW of solar capacity",
      emphasis: true,
      text: "Gas prices rose sharply in 2022. Solar installations were 47% higher than in 2021.",
      figure: <BigNumber
        value="41 GW"
        label="Solar capacity added in the EU"
        delta={0.47}
        deltaLabel="vs 2021"
      />,
    },
    {
      date: "2024",
      title: "Solar supplies 11.1% of EU electricity",
      text: "Coal supplied 9.8%.",
      figure: <BigNumber value="11.1%" label="Solar share of EU electricity" context="Coal supplied 9.8%" />,
    },
  ]}
  source="Ember; SolarPower Europe"
  note="Figures are approximate, for illustration"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/annotated-timeline.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/annotated-timeline.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Before and after (`before-after`)

> Two states of one measure side by side, as figures or small charts, with the change between them stated in the middle.

- Component: `BeforeAfter` (import from `insightcharts`)
- Spec type: `"before-after"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

A single measure at two moments or under two conditions: before and after a policy, control and treatment, last year and this. The change is computed from the two values unless you state it.

### Avoid

More than two states (use `line-chart` or `slope-chart`); many entities each with a before and after (use `dumbbell-chart` or `arrow-chart`); two unrelated figures (use `stat-row`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/before-after
```

The file lands at `components/insightcharts/molecules/before-after.tsx`. `@insightcharts/before-after-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BeforeAfter } from "insightcharts";

<BeforeAfter
  title="Solar module prices fell from $0.74 to $0.15 per watt between 2013 and 2023"
  subtitle="Average price of crystalline silicon modules, US dollars per watt"
  format={{ style: "currency", currency: "USD" }}
  before={{ heading: "2013", value: 0.74, label: "Per watt", context: "2013 average" }}
  after={{ heading: "2023", value: 0.15, label: "Per watt", context: "2023 average" }}
  deltaLabel="in ten years"
  upIsGood={false}
  source="IRENA Renewable Power Generation Costs 2023"
  note="Rounded, approximate figures for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "before-after",
  "title": "Solar module prices fell from $0.74 to $0.15 per watt between 2013 and 2023",
  "subtitle": "Average price of crystalline silicon modules, US dollars per watt",
  "format": { "style": "currency", "currency": "USD" },
  "before": { "heading": "2013", "value": 0.74, "label": "Per watt", "context": "2013 average" },
  "after": { "heading": "2023", "value": 0.15, "label": "Per watt", "context": "2023 average" },
  "deltaLabel": "in ten years",
  "upIsGood": false,
  "source": "IRENA Renewable Power Generation Costs 2023",
  "note": "Rounded, approximate figures for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `before` (required) | `{ heading?, value?, label?, context?, format?, chart? }` |  | The first state: a figure, a chart slot, or both. |
| `after` (required) | `{ heading?, value?, label?, context?, format?, chart? }` |  | The second state. |
| `delta` | `number \| string` |  | The change stated between the two. Default: the relative change when both values are numbers. |
| `deltaLabel` | `string` |  | Words under the change, e.g. "in five years". |
| `deltaFormat` | `FormatSpec` | `signed percent` | Number format for a numeric `delta`. |
| `upIsGood` | `boolean` | `true` | Whether an increase is good news; decides the colour of the change. |
| `format` | `FormatSpec` | `"auto"` | Number format shared by both values. |
| `title` | `string` |  | The change stated plainly, with both values and the period. |
| `subtitle` | `string` |  | Measure and population. |
| `source` | `string` |  | Shown underneath as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to both states. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [big-number](https://insightcharts.dev/llms/big-number.md), [delta](https://insightcharts.dev/llms/delta.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [sparkline](https://insightcharts.dev/llms/sparkline.md)
- Used by: no molecule or template yet

### More examples

#### Two charts, change stated in words

```tsx
import { BarChart, BeforeAfter } from "insightcharts";

<BeforeAfter
  title="The median midday price fell from €44 to €12 per MWh between summer 2019 and summer 2024"
  subtitle="Median day-ahead price by hour, euros per MWh, same scale"
  before={{
    heading: "Summer 2019",
    chart: <BarChart
      data={[
        { hour: "00:00", price: 38 },
        { hour: "03:00", price: 34 },
        { hour: "06:00", price: 41 },
        { hour: "09:00", price: 47 },
        { hour: "12:00", price: 44 },
        { hour: "15:00", price: 43 },
        { hour: "18:00", price: 52 },
        { hour: "21:00", price: 45 },
      ]}
      x="hour"
      y="price"
      orientation="vertical"
      sort="none"
      height={150}
      labels={false}
      option={{ yAxis: { max: 100 } }}
    />,
  }}
  after={{
    heading: "Summer 2024",
    chart: <BarChart
      data={[
        { hour: "00:00", price: 71 },
        { hour: "03:00", price: 64 },
        { hour: "06:00", price: 69 },
        { hour: "09:00", price: 48 },
        { hour: "12:00", price: 12 },
        { hour: "15:00", price: 21 },
        { hour: "18:00", price: 96 },
        { hour: "21:00", price: 84 },
      ]}
      x="hour"
      y="price"
      orientation="vertical"
      sort="none"
      height={150}
      labels={false}
      option={{ yAxis: { max: 100 } }}
    />,
  }}
  delta="−€32"
  deltaLabel="at midday"
  upIsGood={false}
  note="Illustrative data"
/>
```

#### Figures with sparklines

```tsx
import { BeforeAfter, Sparkline } from "insightcharts";

<BeforeAfter
  before={{
    heading: "Before the redesign",
    value: 0.042,
    format: "percent",
    label: "Monthly churn",
    chart: <Sparkline
      data={[{ v: 4.4 }, { v: 4.1 }, { v: 4.3 }, { v: 4.2 }, { v: 4.3 }, { v: 4.2 }]}
      y="v"
    />,
  }}
  after={{
    heading: "After",
    value: 0.021,
    format: "percent",
    label: "Monthly churn",
    chart: <Sparkline
      data={[{ v: 3.6 }, { v: 3.1 }, { v: 2.6 }, { v: 2.4 }, { v: 2.2 }, { v: 2.1 }]}
      y="v"
    />,
  }}
  upIsGood={false}
  deltaLabel="after six months"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/before-after.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/before-after.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Chart with callout (`chart-callout`)

> A chart with a callout beside it that states the main fact. In narrow containers the callout goes underneath.

- Component: `ChartCallout` (import from `insightcharts`)
- Spec type: `"chart-callout"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Whenever a chart needs its meaning stated in words next to it: the standard chart-plus-interpretation unit of a report. The chart's title states the main fact with its number. The callout adds a second fact, a cause or a caveat in plain words.

### Avoid

Repeating the chart title in the callout; long narration (put `prose` before the chart instead); a chart that is already a small tile (the callout would outweigh it).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/chart-callout
```

The file lands at `components/insightcharts/molecules/chart-callout.tsx`. `@insightcharts/chart-callout-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ChartCallout, LineChart } from "insightcharts";

<ChartCallout
  chart={<LineChart
    data={[
      { month: "2024-01-01", rate: 4.2 },
      { month: "2024-02-01", rate: 4.3 },
      { month: "2024-03-01", rate: 4.1 },
      { month: "2024-04-01", rate: 3.6 },
      { month: "2024-05-01", rate: 3.1 },
      { month: "2024-06-01", rate: 2.9 },
      { month: "2024-07-01", rate: 2.6 },
      { month: "2024-08-01", rate: 2.4 },
      { month: "2024-09-01", rate: 2.3 },
      { month: "2024-10-01", rate: 2.2 },
      { month: "2024-11-01", rate: 2.1 },
      { month: "2024-12-01", rate: 2.1 },
    ]}
    x="month"
    y="rate"
    format="{value}%"
    zero
    height={280}
    title="Monthly churn fell from 4.2% to 2.1% in 2024"
    subtitle="Monthly customer churn, 2024"
    source="Internal analytics"
    note="Illustrative data"
    annotations={[{ type: "line", axis: "x", value: "2024-03-01", label: "New onboarding" }]}
  />}
  label="Takeaway"
  lead="Churn fell 2 points after March"
  body="Churn was 4.1% in March, when the new onboarding launched. It fell every month from April to November. It was 2.1% in December."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "chart-callout",
  "chart": {
    "type": "line-chart",
    "data": [
      { "month": "2024-01-01", "rate": 4.2 },
      { "month": "2024-02-01", "rate": 4.3 },
      { "month": "2024-03-01", "rate": 4.1 },
      { "month": "2024-04-01", "rate": 3.6 },
      { "month": "2024-05-01", "rate": 3.1 },
      { "month": "2024-06-01", "rate": 2.9 },
      { "month": "2024-07-01", "rate": 2.6 },
      { "month": "2024-08-01", "rate": 2.4 },
      { "month": "2024-09-01", "rate": 2.3 },
      { "month": "2024-10-01", "rate": 2.2 },
      { "month": "2024-11-01", "rate": 2.1 },
      { "month": "2024-12-01", "rate": 2.1 }
    ],
    "x": "month",
    "y": "rate",
    "format": "{value}%",
    "zero": true,
    "height": 280,
    "title": "Monthly churn fell from 4.2% to 2.1% in 2024",
    "subtitle": "Monthly customer churn, 2024",
    "source": "Internal analytics",
    "note": "Illustrative data",
    "annotations": [{ "type": "line", "axis": "x", "value": "2024-03-01", "label": "New onboarding" }]
  },
  "label": "Takeaway",
  "lead": "Churn fell 2 points after March",
  "body": "Churn was 4.1% in March, when the new onboarding launched. It fell every month from April to November. It was 2.1% in December."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `chart` (required) | `Slot` |  | The chart: a spec or a React element. |
| `lead` | `string` |  | The main fact in a few words, with its number. Shown in bold. |
| `body` | `string` |  | One or two plain sentences that say what the fact means. |
| `tone` | `"neutral" \| "positive" \| "negative" \| "accent"` | `"accent"` | Sets the callout's icon and tint together. |
| `label` | `string` |  | Small label above the lead, e.g. "Takeaway" or "Caveat". |
| `side` | `"left" \| "right"` | `"right"` | Side of the chart the callout sits on. Under 640px it always goes underneath. |
| `variant` | `"plain" \| "soft" \| "outline"` | `"plain"` | `plain` separates the callout with a hairline; the others box it. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Vertical position of the callout beside the chart. |
| `children` | `ReactNode` |  | JSX alternative to `chart`. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the chart and callout. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [callout](https://insightcharts.dev/llms/callout.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md)
- Used by: [executive-brief](https://insightcharts.dev/llms/executive-brief.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Caveat on the left, boxed

```tsx
import { BarChart, ChartCallout } from "insightcharts";

<ChartCallout
  side="left"
  variant="soft"
  tone="negative"
  label="Caveat"
  lead="The new onboarding launched on 11 March"
  body="The March figure includes customers who joined before the launch. April is the first full month on the new onboarding."
  chart={<BarChart
    data={[
      { month: "Jan", rate: 4.2 },
      { month: "Feb", rate: 4.3 },
      { month: "Mar", rate: 4.1 },
      { month: "Apr", rate: 3.6 },
      { month: "May", rate: 3.1 },
      { month: "Jun", rate: 2.9 },
    ]}
    x="month"
    sort="none"
    y="rate"
    format="{value}%"
    orientation="vertical"
    height={260}
    title="Monthly churn fell from 4.1% in March to 2.9% in June 2024"
    subtitle="Monthly customer churn, January to June 2024"
  />}
/>
```

#### Positive, aligned to the top

```tsx
import { ChartCallout, LineChart } from "insightcharts";

<ChartCallout
  tone="positive"
  align="start"
  lead="Churn stayed below 2.5% from August"
  body="Monthly churn was between 2.1% and 2.4% from August to December 2024."
  chart={<LineChart
    data={[
      { month: "2024-01-01", rate: 4.2 },
      { month: "2024-02-01", rate: 4.3 },
      { month: "2024-03-01", rate: 4.1 },
      { month: "2024-04-01", rate: 3.6 },
      { month: "2024-05-01", rate: 3.1 },
      { month: "2024-06-01", rate: 2.9 },
      { month: "2024-07-01", rate: 2.6 },
      { month: "2024-08-01", rate: 2.4 },
      { month: "2024-09-01", rate: 2.3 },
      { month: "2024-10-01", rate: 2.2 },
      { month: "2024-11-01", rate: 2.1 },
      { month: "2024-12-01", rate: 2.1 },
    ]}
    x="month"
    y="rate"
    format="{value}%"
    zero
    height={240}
    title="Monthly churn was 2.1% in December 2024"
    subtitle="Monthly customer churn, 2024"
  />}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/chart-callout.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/chart-callout.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Chart tabs (`chart-tabs`)

> One chart frame with a segmented control that switches between several views of the same data, morphing between views that share a chart type.

- Component: `ChartTabs` (import from `insightcharts`)
- Spec type: `"chart-tabs"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

The same entities under two to five measures or scalings where each view changes the reading: total / per capita / change, absolute / share, linear / log. Give the frame a plain label as its title. Each view's `subtitle` names its measure.

### Avoid

Hiding the most important view behind a tab (show it first, or show both with `small-multiple-grid`); unrelated charts (give each its own figure); more than five views.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/chart-tabs
```

The file lands at `components/insightcharts/molecules/chart-tabs.tsx`. `@insightcharts/chart-tabs-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, ChartTabs, registerComponents } from "insightcharts";

// Specs passed as data are resolved by name when rendered.
registerComponents({ BarChart });

<ChartTabs
  title="CO2 emissions of six large emitters, 2023"
  tabsPosition="below"
  chart={{
    type: "bar-chart",
    data: [
      { country: "China", total: 11.9, perCapita: 8.4, change: 0.38 },
      { country: "United States", total: 4.9, perCapita: 14.3, change: -0.13 },
      { country: "India", total: 3.1, perCapita: 2.1, change: 0.74 },
      { country: "Russia", total: 1.8, perCapita: 12.5, change: 0.1 },
      { country: "Japan", total: 1, perCapita: 8, change: -0.19 },
      { country: "Germany", total: 0.6, perCapita: 7.1, change: -0.28 },
    ],
    x: "country",
    y: "total",
    sort: "desc",
    orientation: "horizontal",
    height: 280,
    highlight: "China",
    format: "{value} Gt",
    subtitle: "CO2 emissions from fossil fuels, billion tonnes, 2023",
  }}
  views={[
    { label: "Total", id: "total" },
    {
      label: "Per capita",
      id: "per-capita",
      props: {
        y: "perCapita",
        highlight: "United States",
        format: "{value} t",
        subtitle: "CO2 emissions per person, tonnes, 2023",
      },
    },
    {
      label: "Change since 2010",
      id: "change",
      props: {
        y: "change",
        highlight: "India",
        format: "percent",
        subtitle: "Change in CO2 emissions, 2010 to 2023",
      },
    },
  ]}
  source="Global Carbon Budget 2024"
  note="Rounded, approximate figures for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "chart-tabs",
  "title": "CO2 emissions of six large emitters, 2023",
  "tabsPosition": "below",
  "chart": {
    "type": "bar-chart",
    "data": [
      { "country": "China", "total": 11.9, "perCapita": 8.4, "change": 0.38 },
      { "country": "United States", "total": 4.9, "perCapita": 14.3, "change": -0.13 },
      { "country": "India", "total": 3.1, "perCapita": 2.1, "change": 0.74 },
      { "country": "Russia", "total": 1.8, "perCapita": 12.5, "change": 0.1 },
      { "country": "Japan", "total": 1, "perCapita": 8, "change": -0.19 },
      { "country": "Germany", "total": 0.6, "perCapita": 7.1, "change": -0.28 }
    ],
    "x": "country",
    "y": "total",
    "sort": "desc",
    "orientation": "horizontal",
    "height": 280,
    "highlight": "China",
    "format": "{value} Gt",
    "subtitle": "CO2 emissions from fossil fuels, billion tonnes, 2023"
  },
  "views": [
    { "label": "Total", "id": "total" },
    {
      "label": "Per capita",
      "id": "per-capita",
      "props": {
        "y": "perCapita",
        "highlight": "United States",
        "format": "{value} t",
        "subtitle": "CO2 emissions per person, tonnes, 2023"
      }
    },
    {
      "label": "Change since 2010",
      "id": "change",
      "props": {
        "y": "change",
        "highlight": "India",
        "format": "percent",
        "subtitle": "Change in CO2 emissions, 2010 to 2023"
      }
    }
  ],
  "source": "Global Carbon Budget 2024",
  "note": "Rounded, approximate figures for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `chart` | `InsightSpec` |  | The base chart spec every view starts from: `{ type, data, ... }`. |
| `views` (required) | `{ label, id?, props?, chart? }[]` |  | Two to five views. `props` are merged over `chart`; or give a view its own complete `chart` slot. |
| `defaultView` | `string \| number` |  | The view shown first: an id, a label or an index. |
| `view` | `string \| number` |  | Controlled active view. |
| `onViewChange` | `(id, index) => void` |  | Called when the reader switches view. |
| `tabsLabel` | `string` | `"Chart view"` | Accessible name of the tab list. |
| `tabsPosition` | `"right" \| "below"` | `"right"` | Tabs beside the title or under it. Under 560px they always go underneath. |
| `title` | `string` |  | A plain label or fact that is true of every view. |
| `subtitle` | `string` |  | What the views share; each view's own `subtitle` names its measure. |
| `source` | `string` |  | Shown under the chart as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `children` | `ReactNode` |  | Extra content under the chart. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the chart. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [line-chart](https://insightcharts.dev/llms/line-chart.md)
- Used by: no molecule or template yet

### More examples

#### Tabs beside the title, a different chart per view

```tsx
import { BarChart, ChartTabs, LineChart } from "insightcharts";

<ChartTabs
  title="Solar supplied 11.1% of EU electricity in 2024"
  defaultView="Trend"
  views={[
    {
      label: "Trend",
      chart: <LineChart
        data={[
          { year: "2019", Solar: 4.2, Coal: 15 },
          { year: "2020", Solar: 5, Coal: 13 },
          { year: "2021", Solar: 5.4, Coal: 14.7 },
          { year: "2022", Solar: 7, Coal: 15.8 },
          { year: "2023", Solar: 9.1, Coal: 12.3 },
          { year: "2024", Solar: 11.1, Coal: 9.8 },
        ]}
        x="year"
        y={["Solar", "Coal"]}
        format="{value}%"
        height={260}
        subtitle="Solar and coal share of EU electricity generation, 2019 to 2024"
      />,
    },
    {
      label: "2024",
      chart: <BarChart
        data={[{ source: "Solar", share: 11.1 }, { source: "Coal", share: 9.8 }]}
        x="source"
        y="share"
        format="{value}%"
        height={260}
        highlight="Solar"
        subtitle="Share of EU electricity generation, 2024. Coal supplied 9.8%."
      />,
    },
  ]}
  source="Ember"
  note="Figures are approximate, for illustration"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/chart-tabs.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/chart-tabs.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Comparison table (`comparison-table`)

> A table whose rows carry inline sparklines, deltas and in-cell bars beside their exact values, from rows and a column config.

- Component: `ComparisonTable` (import from `insightcharts`)
- Spec type: `"comparison-table"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Comparing five to twenty entities on a level, a trend and a change at once: countries, products, teams. Readers look up their row. The sparkline and delta show how the value changed.

### Avoid

Plain lookups with no series (use `data-table`); one measure ranked (use `ranked-list` or `bar-chart`); trends the reader must compare precisely (use `small-multiples`). Each sparkline has its own scale, so it shows the direction of change and cannot be used to compare levels between rows.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/comparison-table
```

The file lands at `components/insightcharts/molecules/comparison-table.tsx`. `@insightcharts/comparison-table-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ComparisonTable } from "insightcharts";

const data = [
  {
    "2019": 40.1,
    "2020": 44.2,
    "2021": 40.9,
    "2022": 44.5,
    "2023": 52.6,
    "2024": 58.9,
    country: "Germany",
    share: 58.9,
    twh: 498,
  },
  {
    "2019": 37.5,
    "2020": 44.1,
    "2021": 46.7,
    "2022": 42.2,
    "2023": 50.3,
    "2024": 56.8,
    country: "Spain",
    share: 56.8,
    twh: 264,
  },
  {
    "2019": 18.2,
    "2020": 26.1,
    "2021": 33,
    "2022": 40.1,
    "2023": 47.7,
    "2024": 52.4,
    country: "Netherlands",
    share: 52.4,
    twh: 121,
  },
  {
    "2019": 39.9,
    "2020": 41.7,
    "2021": 40.3,
    "2022": 35.6,
    "2023": 43.8,
    "2024": 49,
    country: "Italy",
    share: 49,
    twh: 264,
  },
  {
    "2019": 20.9,
    "2020": 24.2,
    "2021": 22.5,
    "2022": 24.4,
    "2023": 27,
    "2024": 28.3,
    country: "France",
    share: 28.3,
    twh: 536,
  },
  {
    "2019": 14.1,
    "2020": 17.2,
    "2021": 16.9,
    "2022": 20.6,
    "2023": 26.4,
    "2024": 29.5,
    country: "Poland",
    share: 29.5,
    twh: 167,
  },
];

<ComparisonTable
  title="The Netherlands' renewable share of electricity rose from 18.2% to 52.4% between 2019 and 2024"
  subtitle="Renewable share of electricity generation, selected EU countries, 2019 to 2024"
  data={data}
  columns={[
    { key: "country", label: "Country" },
    { key: "twh", label: "Generation, TWh", kind: "bar", format: "integer", hideBelow: 560 },
    { key: "share", label: "Share, 2024", format: "{value}%" },
    {
      key: "trend",
      label: "2019 to 2024",
      kind: "sparkline",
      fields: ["2019", "2020", "2021", "2022", "2023", "2024"],
      format: "{value}%",
    },
    {
      key: "change",
      label: "Change",
      kind: "delta",
      fields: ["2019", "2020", "2021", "2022", "2023", "2024"],
      change: "absolute",
      format: "{value} pts",
    },
  ]}
  sort={{ key: "share" }}
  highlight="Netherlands"
  source="Ember, European Electricity Review 2025"
  note="Rounded, illustrative"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "comparison-table",
  "title": "The Netherlands' renewable share of electricity rose from 18.2% to 52.4% between 2019 and 2024",
  "subtitle": "Renewable share of electricity generation, selected EU countries, 2019 to 2024",
  "data": [
    {
      "2019": 40.1,
      "2020": 44.2,
      "2021": 40.9,
      "2022": 44.5,
      "2023": 52.6,
      "2024": 58.9,
      "country": "Germany",
      "share": 58.9,
      "twh": 498
    },
    {
      "2019": 37.5,
      "2020": 44.1,
      "2021": 46.7,
      "2022": 42.2,
      "2023": 50.3,
      "2024": 56.8,
      "country": "Spain",
      "share": 56.8,
      "twh": 264
    },
    {
      "2019": 18.2,
      "2020": 26.1,
      "2021": 33,
      "2022": 40.1,
      "2023": 47.7,
      "2024": 52.4,
      "country": "Netherlands",
      "share": 52.4,
      "twh": 121
    },
    {
      "2019": 39.9,
      "2020": 41.7,
      "2021": 40.3,
      "2022": 35.6,
      "2023": 43.8,
      "2024": 49,
      "country": "Italy",
      "share": 49,
      "twh": 264
    },
    {
      "2019": 20.9,
      "2020": 24.2,
      "2021": 22.5,
      "2022": 24.4,
      "2023": 27,
      "2024": 28.3,
      "country": "France",
      "share": 28.3,
      "twh": 536
    },
    {
      "2019": 14.1,
      "2020": 17.2,
      "2021": 16.9,
      "2022": 20.6,
      "2023": 26.4,
      "2024": 29.5,
      "country": "Poland",
      "share": 29.5,
      "twh": 167
    }
  ],
  "columns": [
    { "key": "country", "label": "Country" },
    {
      "key": "twh",
      "label": "Generation, TWh",
      "kind": "bar",
      "format": "integer",
      "hideBelow": 560
    },
    { "key": "share", "label": "Share, 2024", "format": "{value}%" },
    {
      "key": "trend",
      "label": "2019 to 2024",
      "kind": "sparkline",
      "fields": ["2019", "2020", "2021", "2022", "2023", "2024"],
      "format": "{value}%"
    },
    {
      "key": "change",
      "label": "Change",
      "kind": "delta",
      "fields": ["2019", "2020", "2021", "2022", "2023", "2024"],
      "change": "absolute",
      "format": "{value} pts"
    }
  ],
  "sort": { "key": "share" },
  "highlight": "Netherlands",
  "source": "Ember, European Electricity Review 2025",
  "note": "Rounded, illustrative"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `DataInput` |  | Wide data: one row per entity. Long data: one row per entity and period, with `groupBy`. Omit inside `<InsightData>`. |
| `transform` | `Transform \| Transform[]` |  | Applied before rows are grouped. |
| `columns` (required) | `(string \| { key, label?, kind?, fields?, agg?, change?, format?, upIsGood?, mark?, align?, width?, hideBelow?, sortable? })[]` |  | Columns in order; the first is the row header. `kind` is `text`, `number`, `sparkline`, `delta` or `bar`. For wide data give a sparkline or computed delta its series with `fields`; for long data they use the group's rows. |
| `groupBy` | `string` |  | Long data: the entity field. Rows sharing a value become one table row, in data order. |
| `highlight` | `string \| string[]` |  | Entities to emphasise, matched on the first column. |
| `sort` | `{ key, direction?: "asc" \| "desc" }` |  | Order rows by a column's value. Default direction: descending. With `sortable` this is the opening order. |
| `sortable` | `boolean` | `true` | Click or press Enter on a column header to sort by it (numbers largest first, text A to Z); a second press reverses and a third restores the original order. Sparkline columns do not sort; set `sortable: false` on a column to exclude it. |
| `limit` | `number` |  | Show only the first N rows. |
| `density` | `"comfortable" \| "compact"` | `"comfortable"` | Row padding. |
| `title` | `string` |  | The main fact with its number, or a plain label. Set as the table's `<caption>`. |
| `subtitle` | `string` |  | Units and period. |
| `source` | `string` |  | Shown under the table as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the sparklines and deltas. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [sparkline](https://insightcharts.dev/llms/sparkline.md), [delta](https://insightcharts.dev/llms/delta.md)
- Used by: [scorecard](https://insightcharts.dev/llms/scorecard.md)

### More examples

#### Long data with groupBy, relative change, compact

```tsx
import { ComparisonTable } from "insightcharts";

const data = [
  { country: "Germany", year: "2019", share: 40.1 },
  { country: "Germany", year: "2020", share: 44.2 },
  { country: "Germany", year: "2021", share: 40.9 },
  { country: "Germany", year: "2022", share: 44.5 },
  { country: "Germany", year: "2023", share: 52.6 },
  { country: "Germany", year: "2024", share: 58.9 },
  { country: "Spain", year: "2019", share: 37.5 },
  { country: "Spain", year: "2020", share: 44.1 },
  // ... 28 more rows
];

<ComparisonTable
  data={data}
  groupBy="country"
  density="compact"
  columns={[
    { key: "country", label: "Country" },
    { key: "share", label: "Latest", format: "{value}%" },
    { key: "share", label: "Peak", agg: "max", format: "{value}%", hideBelow: 420 },
    { key: "share", label: "Trend", kind: "sparkline", mark: "bar", format: "{value}%" },
    { key: "share", label: "Since 2019", kind: "delta" },
  ]}
  note="Illustrative data"
/>
```

#### Deltas given in the data, down is good

```tsx
import { ComparisonTable } from "insightcharts";

const data = [
  {
    team: "Onboarding",
    median: "1 h 05 min",
    weekly: [2.4, 2.1, 1.9, 1.6, 1.3, 1.1],
    change: -0.54,
  },
  {
    team: "Technical support",
    median: "2 h 14 min",
    weekly: [4.1, 3.8, 3.2, 2.9, 2.4, 2.2],
    change: -0.46,
  },
  { team: "Billing", median: "3 h 40 min", weekly: [3.1, 3, 3.3, 3.4, 3.6, 3.7], change: 0.19 },
];

<ComparisonTable
  title="Billing's first response time rose 19% over six weeks"
  data={data}
  columns={[
    { key: "team", label: "Team" },
    { key: "median", label: "Median first response", align: "right" },
    { key: "weekly", label: "Last six weeks" },
    { key: "change", label: "Change", kind: "delta", upIsGood: false },
  ]}
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/comparison-table.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/comparison-table.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Filter chips (`filter-chips`)

> The active crossfilter selections of the surrounding `InsightData`, shown as removable chips with a reset control.

- Component: `FilterChips` (import from `insightcharts`)
- Spec type: `"filter-chips"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Inside any `<InsightData>` whose charts use `select`: put it above the charts so readers can see what is filtered, drop one value, or clear everything. `linked-charts` already includes it.

### Avoid

Outside `<InsightData>` it renders nothing unless you pass `selections` yourself. It is not a filter builder: selections are made by clicking marks in the charts.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/filter-chips
```

The file lands at `components/insightcharts/molecules/filter-chips.tsx`. `@insightcharts/filter-chips-demo` adds a ready-made example next to it.

### Usage

```tsx
import { FilterChips } from "insightcharts";

<FilterChips
  labels={{ region: "Region", source: "Source", year: "Year" }}
  selections={{
    "by-region": { field: "region", values: ["Asia", "Europe"] },
    "by-source": { field: "source", values: ["Solar"] },
    "by-year": { field: "year", range: [2020, 2024] },
  }}
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "filter-chips",
  "labels": { "region": "Region", "source": "Source", "year": "Year" },
  "selections": {
    "by-region": { "field": "region", "values": ["Asia", "Europe"] },
    "by-source": { "field": "source", "values": ["Solar"] },
    "by-year": { "field": "year", "range": [2020, 2024] }
  }
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `selections` | `Record<string, { field, values?, range? }>` |  | Selections to show when there is no surrounding `<InsightData>` (or to override it), keyed by owner. Uncontrolled unless `onSelectionsChange` is given. |
| `onSelectionsChange` | `(selections) => void` |  | Called when a chip is removed or the reset is pressed; makes `selections` controlled. |
| `labels` | `Record<string, string>` |  | Display names for field names, e.g. `{ region: "Region" }`. |
| `hint` | `string` |  | Shown while nothing is selected, e.g. "Click a bar to filter". |
| `resetLabel` | `string` | `"Reset"` | Text of the clear-all control. |
| `count` | `boolean` | `false` | Show "1,204 of 5,000 rows" at the end of the line. |
| `unit` | `string` | `"rows"` | Noun for the count, e.g. "orders". |
| `theme` | `ThemeInput` |  | Theme override. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: nothing (it is a primitive)
- Used by: [linked-charts](https://insightcharts.dev/llms/linked-charts.md), [data-explorer](https://insightcharts.dev/llms/data-explorer.md)

### More examples

#### Nothing selected, with a hint

```tsx
import { FilterChips } from "insightcharts";

<FilterChips selections={{}} hint="Click a bar to filter" />
```

### Links

- Registry item: https://insightcharts.dev/r/filter-chips.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/filter-chips.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Hero figure (`hero-figure`)

> The opening exhibit of a piece: kicker, headline and deck above one large chart, with a source line underneath.

- Component: `HeroFigure` (import from `insightcharts`)
- Spec type: `"hero-figure"`
- Level: molecule. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

At the very top of a data story or a one-page report. The headline states the main fact with its number. The chart shows that fact.

### Avoid

Giving the chart its own `title` (the headline is the title; use the chart's `subtitle` for the measure). A second hero on the same page: later sections use `section` or `chart-callout`.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/hero-figure
```

The file lands at `components/insightcharts/molecules/hero-figure.tsx`. `@insightcharts/hero-figure-demo` adds a ready-made example next to it.

### Usage

```tsx
import { HeroFigure, LineChart } from "insightcharts";

<HeroFigure
  kicker="Energy transition"
  title="Solar supplied 11.1% of EU electricity in 2024"
  deck="Coal's share fell from 24.6% in 2015 to 9.8% in 2024."
  byline="By Ana Ruiz"
  date="2025-01-23"
  chart={<LineChart
    data={[
      { year: "2015", Solar: 2.9, Coal: 24.6 },
      { year: "2016", Solar: 3, Coal: 22 },
      { year: "2017", Solar: 3.4, Coal: 20.6 },
      { year: "2018", Solar: 3.7, Coal: 19.2 },
      { year: "2019", Solar: 4.2, Coal: 15 },
      { year: "2020", Solar: 5, Coal: 13 },
      { year: "2021", Solar: 5.4, Coal: 14.7 },
      { year: "2022", Solar: 7, Coal: 15.8 },
      { year: "2023", Solar: 9.1, Coal: 12.3 },
      { year: "2024", Solar: 11.1, Coal: 9.8 },
    ]}
    x="year"
    y={["Solar", "Coal"]}
    format="{value}%"
    zero
    height={380}
    subtitle="Solar and coal share of EU electricity generation, 2015 to 2024"
    annotations={[{ type: "point", x: "2024", y: 11.1, label: "Solar 11.1%", position: "left" }]}
  />}
  source={{ name: "Ember, European Electricity Review 2025", url: "https://ember-energy.org" }}
  note="Figures are approximate, for illustration"
  period="2015 to 2024"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "hero-figure",
  "kicker": "Energy transition",
  "title": "Solar supplied 11.1% of EU electricity in 2024",
  "deck": "Coal's share fell from 24.6% in 2015 to 9.8% in 2024.",
  "byline": "By Ana Ruiz",
  "date": "2025-01-23",
  "chart": {
    "type": "line-chart",
    "data": [
      { "year": "2015", "Solar": 2.9, "Coal": 24.6 },
      { "year": "2016", "Solar": 3, "Coal": 22 },
      { "year": "2017", "Solar": 3.4, "Coal": 20.6 },
      { "year": "2018", "Solar": 3.7, "Coal": 19.2 },
      { "year": "2019", "Solar": 4.2, "Coal": 15 },
      { "year": "2020", "Solar": 5, "Coal": 13 },
      { "year": "2021", "Solar": 5.4, "Coal": 14.7 },
      { "year": "2022", "Solar": 7, "Coal": 15.8 },
      { "year": "2023", "Solar": 9.1, "Coal": 12.3 },
      { "year": "2024", "Solar": 11.1, "Coal": 9.8 }
    ],
    "x": "year",
    "y": ["Solar", "Coal"],
    "format": "{value}%",
    "zero": true,
    "height": 380,
    "subtitle": "Solar and coal share of EU electricity generation, 2015 to 2024",
    "annotations": [{ "type": "point", "x": "2024", "y": 11.1, "label": "Solar 11.1%", "position": "left" }]
  },
  "source": { "name": "Ember, European Electricity Review 2025", "url": "https://ember-energy.org" },
  "note": "Figures are approximate, for illustration",
  "period": "2015 to 2024"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The main fact, as one plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the series or topic. |
| `deck` | `string` |  | One plain sentence under the title that adds a second fact. |
| `byline` | `string` |  | Author line, e.g. "By Ana Ruiz". |
| `date` | `string` |  | Publication date. ISO dates are formatted for the locale. |
| `chart` (required) | `Slot` |  | The hero chart: a spec or a React element, without its own title. |
| `source` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `note` | `string` |  | Caveats the reader should know. |
| `align` | `"left" \| "center"` | `"left"` | Headline alignment. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title. |
| `children` | `ReactNode` |  | JSX alternative to `chart`. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the headline, chart and source note. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [source-note](https://insightcharts.dev/llms/source-note.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [big-number](https://insightcharts.dev/llms/big-number.md)
- Used by: no molecule or template yet

### More examples

#### Centered, big number as the exhibit

```tsx
import { BigNumber, HeroFigure } from "insightcharts";

<HeroFigure
  align="center"
  title="33% of the world's population had never used the internet in 2023"
  deck="The ITU estimates that 2.6 billion people were offline."
  chart={<BigNumber
    size="hero"
    align="center"
    value="2.6 billion"
    label="People who have never used the internet"
    context="33% of the world's population in 2023"
  />}
  source="ITU Facts and Figures 2023"
  note="Figures are approximate, for illustration"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/hero-figure.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/hero-figure.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## KPI grid (`kpi-grid`)

> A responsive grid of trend cards drawn from one dataset: each metric shows its latest value, its change and a sparkline.

- Component: `KpiGrid` (import from `insightcharts`)
- Spec type: `"kpi-grid"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

The top of a dashboard or a monthly report: three to eight metrics tracked over the same periods. Pass one table with a column per metric.

### Avoid

Figures without a series behind them (use `stat-row`); comparing the metrics with each other on one scale (use `line-chart` or `small-multiples`); more than eight cards.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/kpi-grid
```

The file lands at `components/insightcharts/molecules/kpi-grid.tsx`. `@insightcharts/kpi-grid-demo` adds a ready-made example next to it.

### Usage

```tsx
import { KpiGrid } from "insightcharts";

const data = [
  { month: "2024-01-01", users: 38100, mrr: 412000, churn: 4.2, response: 4.1 },
  { month: "2024-02-01", users: 39400, mrr: 428000, churn: 4, response: 3.9 },
  { month: "2024-03-01", users: 39000, mrr: 431000, churn: 3.9, response: 3.8 },
  { month: "2024-04-01", users: 40800, mrr: 455000, churn: 3.6, response: 3.2 },
  { month: "2024-05-01", users: 42200, mrr: 470000, churn: 3.1, response: 3.4 },
  { month: "2024-06-01", users: 41900, mrr: 476000, churn: 2.9, response: 2.9 },
  { month: "2024-07-01", users: 43500, mrr: 498000, churn: 2.6, response: 2.7 },
  { month: "2024-08-01", users: 44100, mrr: 511000, churn: 2.4, response: 2.6 },
  { month: "2024-09-01", users: 44500, mrr: 524000, churn: 2.3, response: 2.4 },
  { month: "2024-10-01", users: 46000, mrr: 548000, churn: 2.2, response: 2.3 },
  { month: "2024-11-01", users: 47200, mrr: 566000, churn: 2.1, response: 2.2 },
  { month: "2024-12-01", users: 48200, mrr: 589000, churn: 2.1, response: 2.2 },
];

<KpiGrid
  title="Monthly active users rose from 38,100 to 48,200 in 2024"
  subtitle="Four product metrics by month, 2024. Change is measured against January."
  data={data}
  x="month"
  metrics={[
    { y: "users", label: "Monthly active users", format: "compact" },
    { y: "mrr", label: "Recurring revenue", format: "currency:USD" },
    { y: "churn", label: "Monthly churn", format: "{value}%", change: "absolute", upIsGood: false },
    { y: "response", label: "Median first response", format: "{value} h", upIsGood: false },
  ]}
  source="Internal analytics"
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "kpi-grid",
  "title": "Monthly active users rose from 38,100 to 48,200 in 2024",
  "subtitle": "Four product metrics by month, 2024. Change is measured against January.",
  "data": [
    { "month": "2024-01-01", "users": 38100, "mrr": 412000, "churn": 4.2, "response": 4.1 },
    { "month": "2024-02-01", "users": 39400, "mrr": 428000, "churn": 4, "response": 3.9 },
    { "month": "2024-03-01", "users": 39000, "mrr": 431000, "churn": 3.9, "response": 3.8 },
    { "month": "2024-04-01", "users": 40800, "mrr": 455000, "churn": 3.6, "response": 3.2 },
    { "month": "2024-05-01", "users": 42200, "mrr": 470000, "churn": 3.1, "response": 3.4 },
    { "month": "2024-06-01", "users": 41900, "mrr": 476000, "churn": 2.9, "response": 2.9 },
    { "month": "2024-07-01", "users": 43500, "mrr": 498000, "churn": 2.6, "response": 2.7 },
    { "month": "2024-08-01", "users": 44100, "mrr": 511000, "churn": 2.4, "response": 2.6 },
    { "month": "2024-09-01", "users": 44500, "mrr": 524000, "churn": 2.3, "response": 2.4 },
    { "month": "2024-10-01", "users": 46000, "mrr": 548000, "churn": 2.2, "response": 2.3 },
    { "month": "2024-11-01", "users": 47200, "mrr": 566000, "churn": 2.1, "response": 2.2 },
    { "month": "2024-12-01", "users": 48200, "mrr": 589000, "churn": 2.1, "response": 2.2 }
  ],
  "x": "month",
  "metrics": [
    { "y": "users", "label": "Monthly active users", "format": "compact" },
    { "y": "mrr", "label": "Recurring revenue", "format": "currency:USD" },
    {
      "y": "churn",
      "label": "Monthly churn",
      "format": "{value}%",
      "change": "absolute",
      "upIsGood": false
    },
    { "y": "response", "label": "Median first response", "format": "{value} h", "upIsGood": false }
  ],
  "source": "Internal analytics",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `DataInput` |  | One dataset in time order: a row per period, a column per metric. Omit inside `<InsightData>`. |
| `transform` | `Transform \| Transform[]` |  | Applied once, before the cards read the rows. |
| `x` | `string` |  | Period field shared by every metric. |
| `metrics` (required) | `{ y, label, format?, upIsGood?, compare?, change?, deltaFormat?, deltaLabel?, context?, value?, delta?, kind? }[]` |  | One card per metric; each takes the props of `trend-card`. |
| `compare` | `"first" \| "previous" \| number` | `"first"` | Baseline for every card's change; a metric can override it. |
| `change` | `"percent" \| "absolute"` | `"percent"` | Relative change, or the difference between the two values; a metric can override it. An absolute change of a percentage metric is shown in percentage points ("−2.1 pts"). |
| `deltaFormat` | `FormatSpec` |  | Format for absolute changes, e.g. `"{value} pp"` or `"signed"`; a metric can override it. Default: points for percentage formats, otherwise the metric's own `format`. |
| `columns` | `number` |  | Preferred columns. Default: up to four, reduced to fit cards of at least 200px. |
| `title` | `string` |  | The main fact with its number, or a plain label. |
| `subtitle` | `string` |  | Population and period. |
| `source` | `string` |  | Shown under the grid as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to every card. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [trend-card](https://insightcharts.dev/llms/trend-card.md)
- Used by: [scorecard](https://insightcharts.dev/llms/scorecard.md)

### More examples

#### Two columns, change against the previous month

```tsx
import { KpiGrid } from "insightcharts";

const data = [
  { month: "2024-01-01", users: 38100, mrr: 412000, churn: 4.2, response: 4.1 },
  { month: "2024-02-01", users: 39400, mrr: 428000, churn: 4, response: 3.9 },
  { month: "2024-03-01", users: 39000, mrr: 431000, churn: 3.9, response: 3.8 },
  { month: "2024-04-01", users: 40800, mrr: 455000, churn: 3.6, response: 3.2 },
  { month: "2024-05-01", users: 42200, mrr: 470000, churn: 3.1, response: 3.4 },
  { month: "2024-06-01", users: 41900, mrr: 476000, churn: 2.9, response: 2.9 },
  { month: "2024-07-01", users: 43500, mrr: 498000, churn: 2.6, response: 2.7 },
  { month: "2024-08-01", users: 44100, mrr: 511000, churn: 2.4, response: 2.6 },
  // ... 4 more rows
];

<KpiGrid
  data={data}
  x="month"
  compare="previous"
  columns={2}
  metrics={[
    { y: "users", label: "Monthly active users", format: "compact" },
    { y: "mrr", label: "Recurring revenue", format: "currency:USD", kind: "bar" },
  ]}
/>
```

#### Six metrics

```tsx
import { KpiGrid } from "insightcharts";

const data = [
  {
    month: "2024-01-01",
    users: 38100,
    mrr: 412000,
    churn: 4.2,
    response: 4.1,
    nps: 31,
    tickets: 1840,
  },
  {
    month: "2024-02-01",
    users: 39400,
    mrr: 428000,
    churn: 4,
    response: 3.9,
    nps: 32,
    tickets: 1778,
  },
  {
    month: "2024-03-01",
    users: 39000,
    mrr: 431000,
    churn: 3.9,
    response: 3.8,
    nps: 34,
    tickets: 1716,
  },
  {
    month: "2024-04-01",
    users: 40800,
    mrr: 455000,
    churn: 3.6,
    response: 3.2,
    nps: 35,
    tickets: 1654,
  },
  {
    month: "2024-05-01",
    users: 42200,
    mrr: 470000,
    churn: 3.1,
    response: 3.4,
    nps: 37,
    tickets: 1592,
  },
  {
    month: "2024-06-01",
    users: 41900,
    mrr: 476000,
    churn: 2.9,
    response: 2.9,
    nps: 38,
    tickets: 1530,
  },
  {
    month: "2024-07-01",
    users: 43500,
    mrr: 498000,
    churn: 2.6,
    response: 2.7,
    nps: 39,
    tickets: 1468,
  },
  {
    month: "2024-08-01",
    users: 44100,
    mrr: 511000,
    churn: 2.4,
    response: 2.6,
    nps: 41,
    tickets: 1406,
  },
  // ... 4 more rows
];

<KpiGrid
  data={data}
  x="month"
  metrics={[
    { y: "users", label: "Monthly active users", format: "compact" },
    { y: "mrr", label: "Recurring revenue", format: "currency:USD" },
    { y: "churn", label: "Monthly churn", format: "{value}%", change: "absolute", upIsGood: false },
    { y: "response", label: "Median first response", format: "{value} h", upIsGood: false },
    { y: "nps", label: "Net promoter score", change: "absolute" },
    { y: "tickets", label: "Support tickets", upIsGood: false },
  ]}
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/kpi-grid.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/kpi-grid.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Linked charts (`linked-charts`)

> Two to four charts over one shared dataset in a responsive grid: clicking a mark in one filters the others, with the active filters shown as removable chips.

- Component: `LinkedCharts` (import from `insightcharts`)
- Spec type: `"linked-charts"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Exploration of one table along several dimensions: by region, by category and over time. Pass row-level data once; each chart aggregates it with its own `transform`, sets `select: true` and omits `data`.

### Avoid

A report that states one fixed fact (use `chart-callout` or `scrolly-chart`); charts over unrelated datasets (they cannot filter each other); more than four charts.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/linked-charts
```

The file lands at `components/insightcharts/molecules/linked-charts.tsx`. `@insightcharts/linked-charts-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, LinkedCharts } from "insightcharts";

const data = [
  { region: "Asia", year: "2020", source: "Hydro", twh: 1810 },
  { region: "Asia", year: "2020", source: "Wind", twh: 480 },
  { region: "Asia", year: "2020", source: "Solar", twh: 420 },
  { region: "Asia", year: "2021", source: "Hydro", twh: 1790 },
  { region: "Asia", year: "2021", source: "Wind", twh: 590 },
  { region: "Asia", year: "2021", source: "Solar", twh: 560 },
  { region: "Asia", year: "2022", source: "Hydro", twh: 1830 },
  { region: "Asia", year: "2022", source: "Wind", twh: 700 },
  { region: "Asia", year: "2022", source: "Solar", twh: 730 },
  { region: "Asia", year: "2023", source: "Hydro", twh: 1800 },
  { region: "Asia", year: "2023", source: "Wind", twh: 880 },
  { region: "Asia", year: "2023", source: "Solar", twh: 980 },
  { region: "Asia", year: "2024", source: "Hydro", twh: 1860 },
  { region: "Asia", year: "2024", source: "Wind", twh: 1010 },
  { region: "Asia", year: "2024", source: "Solar", twh: 1290 },
  { region: "Europe", year: "2020", source: "Hydro", twh: 640 },
  { region: "Europe", year: "2020", source: "Wind", twh: 510 },
  { region: "Europe", year: "2020", source: "Solar", twh: 190 },
  { region: "Europe", year: "2021", source: "Hydro", twh: 620 },
  { region: "Europe", year: "2021", source: "Wind", twh: 540 },
  { region: "Europe", year: "2021", source: "Solar", twh: 220 },
  { region: "Europe", year: "2022", source: "Hydro", twh: 560 },
  { region: "Europe", year: "2022", source: "Wind", twh: 580 },
  { region: "Europe", year: "2022", source: "Solar", twh: 270 },
  { region: "Europe", year: "2023", source: "Hydro", twh: 610 },
  { region: "Europe", year: "2023", source: "Wind", twh: 640 },
  { region: "Europe", year: "2023", source: "Solar", twh: 330 },
  { region: "Europe", year: "2024", source: "Hydro", twh: 650 },
  { region: "Europe", year: "2024", source: "Wind", twh: 690 },
  { region: "Europe", year: "2024", source: "Solar", twh: 390 },
  { region: "North America", year: "2020", source: "Hydro", twh: 690 },
  { region: "North America", year: "2020", source: "Wind", twh: 400 },
  { region: "North America", year: "2020", source: "Solar", twh: 150 },
  { region: "North America", year: "2021", source: "Hydro", twh: 680 },
  { region: "North America", year: "2021", source: "Wind", twh: 450 },
  { region: "North America", year: "2021", source: "Solar", twh: 190 },
  { region: "North America", year: "2022", source: "Hydro", twh: 700 },
  { region: "North America", year: "2022", source: "Wind", twh: 500 },
  { region: "North America", year: "2022", source: "Solar", twh: 240 },
  { region: "North America", year: "2023", source: "Hydro", twh: 660 },
  { region: "North America", year: "2023", source: "Wind", twh: 520 },
  { region: "North America", year: "2023", source: "Solar", twh: 290 },
  { region: "North America", year: "2024", source: "Hydro", twh: 670 },
  { region: "North America", year: "2024", source: "Wind", twh: 560 },
  { region: "North America", year: "2024", source: "Solar", twh: 360 },
  { region: "Latin America", year: "2020", source: "Hydro", twh: 720 },
  { region: "Latin America", year: "2020", source: "Wind", twh: 120 },
  { region: "Latin America", year: "2020", source: "Solar", twh: 40 },
  { region: "Latin America", year: "2021", source: "Hydro", twh: 690 },
  { region: "Latin America", year: "2021", source: "Wind", twh: 140 },
  { region: "Latin America", year: "2021", source: "Solar", twh: 60 },
  { region: "Latin America", year: "2022", source: "Hydro", twh: 740 },
  { region: "Latin America", year: "2022", source: "Wind", twh: 170 },
  { region: "Latin America", year: "2022", source: "Solar", twh: 90 },
  { region: "Latin America", year: "2023", source: "Hydro", twh: 760 },
  { region: "Latin America", year: "2023", source: "Wind", twh: 200 },
  { region: "Latin America", year: "2023", source: "Solar", twh: 120 },
  { region: "Latin America", year: "2024", source: "Hydro", twh: 730 },
  { region: "Latin America", year: "2024", source: "Wind", twh: 230 },
  { region: "Latin America", year: "2024", source: "Solar", twh: 160 },
];

<LinkedCharts
  title="Asia generated 46% of the renewable electricity in these four regions from 2020 to 2024"
  subtitle="Electricity generation from hydro, wind and solar, TWh, four regions, 2020 to 2024"
  data={data}
  labels={{ region: "Region", source: "Source", year: "Year" }}
  hint="Click a bar to filter the other charts"
  count
  charts={[
    <BarChart
      id="by-region"
      x="region"
      y="twh"
      select
      format="compact"
      height={200}
      title="By region"
      transform={{ type: "aggregate", groupBy: "region", measures: { twh: { op: "sum", field: "twh" } } }}
    />,
    <BarChart
      id="by-source"
      x="source"
      y="twh"
      select
      format="compact"
      height={200}
      title="By source"
      transform={{ type: "aggregate", groupBy: "source", measures: { twh: { op: "sum", field: "twh" } } }}
    />,
    <BarChart
      id="by-year"
      x="year"
      y="twh"
      series="source"
      stack
      orientation="vertical"
      sort="none"
      select="year"
      format="compact"
      height={240}
      title="By year"
      transform={{
        type: "aggregate",
        groupBy: ["year", "source"],
        measures: { twh: { op: "sum", field: "twh" } },
      }}
    />,
  ]}
  source="Ember, Global Electricity Review 2025"
  note="Regional figures rounded, illustrative"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "linked-charts",
  "title": "Asia generated 46% of the renewable electricity in these four regions from 2020 to 2024",
  "subtitle": "Electricity generation from hydro, wind and solar, TWh, four regions, 2020 to 2024",
  "data": [
    { "region": "Asia", "year": "2020", "source": "Hydro", "twh": 1810 },
    { "region": "Asia", "year": "2020", "source": "Wind", "twh": 480 },
    { "region": "Asia", "year": "2020", "source": "Solar", "twh": 420 },
    { "region": "Asia", "year": "2021", "source": "Hydro", "twh": 1790 },
    { "region": "Asia", "year": "2021", "source": "Wind", "twh": 590 },
    { "region": "Asia", "year": "2021", "source": "Solar", "twh": 560 },
    { "region": "Asia", "year": "2022", "source": "Hydro", "twh": 1830 },
    { "region": "Asia", "year": "2022", "source": "Wind", "twh": 700 },
    { "region": "Asia", "year": "2022", "source": "Solar", "twh": 730 },
    { "region": "Asia", "year": "2023", "source": "Hydro", "twh": 1800 },
    { "region": "Asia", "year": "2023", "source": "Wind", "twh": 880 },
    { "region": "Asia", "year": "2023", "source": "Solar", "twh": 980 },
    { "region": "Asia", "year": "2024", "source": "Hydro", "twh": 1860 },
    { "region": "Asia", "year": "2024", "source": "Wind", "twh": 1010 },
    { "region": "Asia", "year": "2024", "source": "Solar", "twh": 1290 },
    { "region": "Europe", "year": "2020", "source": "Hydro", "twh": 640 },
    { "region": "Europe", "year": "2020", "source": "Wind", "twh": 510 },
    { "region": "Europe", "year": "2020", "source": "Solar", "twh": 190 },
    { "region": "Europe", "year": "2021", "source": "Hydro", "twh": 620 },
    { "region": "Europe", "year": "2021", "source": "Wind", "twh": 540 },
    { "region": "Europe", "year": "2021", "source": "Solar", "twh": 220 },
    { "region": "Europe", "year": "2022", "source": "Hydro", "twh": 560 },
    { "region": "Europe", "year": "2022", "source": "Wind", "twh": 580 },
    { "region": "Europe", "year": "2022", "source": "Solar", "twh": 270 },
    { "region": "Europe", "year": "2023", "source": "Hydro", "twh": 610 },
    { "region": "Europe", "year": "2023", "source": "Wind", "twh": 640 },
    { "region": "Europe", "year": "2023", "source": "Solar", "twh": 330 },
    { "region": "Europe", "year": "2024", "source": "Hydro", "twh": 650 },
    { "region": "Europe", "year": "2024", "source": "Wind", "twh": 690 },
    { "region": "Europe", "year": "2024", "source": "Solar", "twh": 390 },
    { "region": "North America", "year": "2020", "source": "Hydro", "twh": 690 },
    { "region": "North America", "year": "2020", "source": "Wind", "twh": 400 },
    { "region": "North America", "year": "2020", "source": "Solar", "twh": 150 },
    { "region": "North America", "year": "2021", "source": "Hydro", "twh": 680 },
    { "region": "North America", "year": "2021", "source": "Wind", "twh": 450 },
    { "region": "North America", "year": "2021", "source": "Solar", "twh": 190 },
    { "region": "North America", "year": "2022", "source": "Hydro", "twh": 700 },
    { "region": "North America", "year": "2022", "source": "Wind", "twh": 500 },
    { "region": "North America", "year": "2022", "source": "Solar", "twh": 240 },
    { "region": "North America", "year": "2023", "source": "Hydro", "twh": 660 },
    { "region": "North America", "year": "2023", "source": "Wind", "twh": 520 },
    { "region": "North America", "year": "2023", "source": "Solar", "twh": 290 },
    { "region": "North America", "year": "2024", "source": "Hydro", "twh": 670 },
    { "region": "North America", "year": "2024", "source": "Wind", "twh": 560 },
    { "region": "North America", "year": "2024", "source": "Solar", "twh": 360 },
    { "region": "Latin America", "year": "2020", "source": "Hydro", "twh": 720 },
    { "region": "Latin America", "year": "2020", "source": "Wind", "twh": 120 },
    { "region": "Latin America", "year": "2020", "source": "Solar", "twh": 40 },
    { "region": "Latin America", "year": "2021", "source": "Hydro", "twh": 690 },
    { "region": "Latin America", "year": "2021", "source": "Wind", "twh": 140 },
    { "region": "Latin America", "year": "2021", "source": "Solar", "twh": 60 },
    { "region": "Latin America", "year": "2022", "source": "Hydro", "twh": 740 },
    { "region": "Latin America", "year": "2022", "source": "Wind", "twh": 170 },
    { "region": "Latin America", "year": "2022", "source": "Solar", "twh": 90 },
    { "region": "Latin America", "year": "2023", "source": "Hydro", "twh": 760 },
    { "region": "Latin America", "year": "2023", "source": "Wind", "twh": 200 },
    { "region": "Latin America", "year": "2023", "source": "Solar", "twh": 120 },
    { "region": "Latin America", "year": "2024", "source": "Hydro", "twh": 730 },
    { "region": "Latin America", "year": "2024", "source": "Wind", "twh": 230 },
    { "region": "Latin America", "year": "2024", "source": "Solar", "twh": 160 }
  ],
  "labels": { "region": "Region", "source": "Source", "year": "Year" },
  "hint": "Click a bar to filter the other charts",
  "count": true,
  "charts": [
    {
      "type": "bar-chart",
      "id": "by-region",
      "x": "region",
      "y": "twh",
      "select": true,
      "format": "compact",
      "height": 200,
      "title": "By region",
      "transform": {
        "type": "aggregate",
        "groupBy": "region",
        "measures": { "twh": { "op": "sum", "field": "twh" } }
      }
    },
    {
      "type": "bar-chart",
      "id": "by-source",
      "x": "source",
      "y": "twh",
      "select": true,
      "format": "compact",
      "height": 200,
      "title": "By source",
      "transform": {
        "type": "aggregate",
        "groupBy": "source",
        "measures": { "twh": { "op": "sum", "field": "twh" } }
      }
    },
    {
      "type": "bar-chart",
      "id": "by-year",
      "x": "year",
      "y": "twh",
      "series": "source",
      "stack": true,
      "orientation": "vertical",
      "sort": "none",
      "select": "year",
      "format": "compact",
      "height": 240,
      "title": "By year",
      "transform": {
        "type": "aggregate",
        "groupBy": ["year", "source"],
        "measures": { "twh": { "op": "sum", "field": "twh" } }
      }
    }
  ],
  "source": "Ember, Global Electricity Review 2025",
  "note": "Regional figures rounded, illustrative"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` (required) | `DataInput` |  | The shared, row-level dataset. |
| `transform` | `Transform \| Transform[]` |  | Applied once to the shared data. |
| `charts` | `Slot[]` |  | Two to four chart specs or elements. Give each `select: true` (or a field name) and a stable `id`, and leave out `data`. |
| `columns` | `number` |  | Preferred columns. Default two; fewer when charts would be narrower than `minChartWidth`. |
| `minChartWidth` | `number` | `260` | Narrowest a chart may get before the grid drops a column. |
| `filters` | `boolean` | `true` | Show the filter line (`filter-chips`). |
| `hint` | `string` | `"Click a mark to filter the other charts"` | Shown in the filter line while nothing is selected. |
| `labels` | `Record<string, string>` |  | Display names for the fields in the chips. |
| `count` | `boolean` | `false` | Show the filtered row count at the end of the filter line. |
| `unit` | `string` | `"rows"` | Noun for the count. |
| `selections` | `Record<string, Selection>` |  | Controlled selections, keyed by chart id. |
| `onSelectionsChange` | `(selections) => void` |  | Called when the selections change. |
| `title` | `string` |  | Heading for the group. |
| `subtitle` | `string` |  | Measure, population and period shared by the charts. |
| `source` | `string` |  | Shown under the grid as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `children` | `ReactNode` |  | JSX alternative to `charts`. |
| `before` | `Slot \| Slot[]` |  | Content rendered inside the shared store above the grid: figures, text, a custom component that calls `useInsightData()`, or a spec that omits `data` (e.g. `stat-row`, `data-table`). It sees the same filtered rows as the charts. |
| `after` | `Slot \| Slot[]` |  | Content rendered inside the shared store below the grid, e.g. a detail table of the filtered rows. |
| `gap` | `number` | `24` | Space in px between the `before` slot, the grid and the `after` slot. |
| `theme` | `ThemeInput` |  | Theme override, passed on to every chart. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [filter-chips](https://insightcharts.dev/llms/filter-chips.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [line-chart](https://insightcharts.dev/llms/line-chart.md)
- Used by: [data-explorer](https://insightcharts.dev/llms/data-explorer.md)

### More examples

#### Two charts, no row count

```tsx
import { BarChart, LineChart, LinkedCharts } from "insightcharts";

const data = [
  { region: "Asia", year: "2020", source: "Hydro", twh: 1810 },
  { region: "Asia", year: "2020", source: "Wind", twh: 480 },
  { region: "Asia", year: "2020", source: "Solar", twh: 420 },
  { region: "Asia", year: "2021", source: "Hydro", twh: 1790 },
  { region: "Asia", year: "2021", source: "Wind", twh: 590 },
  { region: "Asia", year: "2021", source: "Solar", twh: 560 },
  { region: "Asia", year: "2022", source: "Hydro", twh: 1830 },
  { region: "Asia", year: "2022", source: "Wind", twh: 700 },
  // ... 52 more rows
];

<LinkedCharts
  data={data}
  labels={{ region: "Region", year: "Year" }}
  charts={[
    <BarChart
      id="pair-region"
      x="region"
      y="twh"
      select
      format="compact"
      height={200}
      title="Generation by region"
      transform={{ type: "aggregate", groupBy: "region", measures: { twh: { op: "sum", field: "twh" } } }}
    />,
    <LineChart
      id="pair-year"
      x="year"
      y="twh"
      series="source"
      format="compact"
      height={200}
      title="Generation by source over time"
      transform={{
        type: "aggregate",
        groupBy: ["year", "source"],
        measures: { twh: { op: "sum", field: "twh" } },
      }}
    />,
  ]}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/linked-charts.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/linked-charts.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Metric breakdown (`metric-breakdown`)

> A headline number with its composition underneath: one segmented bar and a key giving each part's value and share.

- Component: `MetricBreakdown` (import from `insightcharts`)
- Spec type: `"metric-breakdown"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

A total that the reader will immediately want split: a budget by department, revenue by product line, emissions by sector. Two to six parts that add up to the number above them.

### Avoid

Parts that do not sum to the headline; more than about six parts (use `bar-chart`); composition compared across groups or over time (use `bar-chart` with `stack: "percent"` or `area-chart`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/metric-breakdown
```

The file lands at `components/insightcharts/molecules/metric-breakdown.tsx`. `@insightcharts/metric-breakdown-demo` adds a ready-made example next to it.

### Usage

```tsx
import { MetricBreakdown } from "insightcharts";

const data = [
  { sector: "Energy supply", mt: 862 },
  { sector: "Transport", mt: 804 },
  { sector: "Industry", mt: 701 },
  { sector: "Buildings", mt: 437 },
  { sector: "Agriculture", mt: 378 },
  { sector: "Waste", mt: 109 },
];

<MetricBreakdown
  label="Greenhouse gas emissions, EU-27, 2022"
  context="Million tonnes of CO2 equivalent. 31% below the 1990 level."
  data={data}
  name="sector"
  value="mt"
  format="integer"
  source="European Environment Agency"
  note="Rounded, approximate figures for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "metric-breakdown",
  "label": "Greenhouse gas emissions, EU-27, 2022",
  "context": "Million tonnes of CO2 equivalent. 31% below the 1990 level.",
  "data": [
    { "sector": "Energy supply", "mt": 862 },
    { "sector": "Transport", "mt": 804 },
    { "sector": "Industry", "mt": 701 },
    { "sector": "Buildings", "mt": 437 },
    { "sector": "Agriculture", "mt": 378 },
    { "sector": "Waste", "mt": 109 }
  ],
  "name": "sector",
  "value": "mt",
  "format": "integer",
  "source": "European Environment Agency",
  "note": "Rounded, approximate figures for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` (required) | `string` |  | What the headline number measures. |
| `data` | `DataInput` |  | One row per part. Omit inside `<InsightData>`. |
| `transform` | `Transform \| Transform[]` |  | Applied before the parts are summed. |
| `name` (required) | `string` |  | Field naming each part. |
| `value` (required) | `string` |  | Field with each part's value. |
| `total` | `number \| string` |  | The headline number. Default: the sum of the parts. |
| `context` | `string` |  | The line under the headline number. |
| `delta` | `number \| string` |  | Change in the headline number. Numbers render as signed percentages. |
| `deltaLabel` | `string` |  | What the delta is against. |
| `upIsGood` | `boolean` | `true` | Whether an increase is good news. |
| `size` | `"hero" \| "stat"` | `"stat"` | `hero` when this opens a piece. |
| `show` | `"both" \| "value" \| "share"` | `"both"` | What the key prints beside each part. |
| `sort` | `"none" \| "desc"` | `"none"` | Order parts by size; the bar and the key follow. |
| `names` | `Record<string, string>` |  | Display names for part keys. |
| `format` | `FormatSpec` | `"auto"` | Number format for the headline and the parts. |
| `source` | `string` |  | Shown underneath as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the number and the bar. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [big-number](https://insightcharts.dev/llms/big-number.md), [segmented-bar](https://insightcharts.dev/llms/segmented-bar.md)
- Used by: no molecule or template yet

### More examples

#### Three parts, shares only

```tsx
import { MetricBreakdown } from "insightcharts";

const data = [
  { plan: "Enterprise", mrr: 318000 },
  { plan: "Team", mrr: 201000 },
  { plan: "Starter", mrr: 70000 },
];

<MetricBreakdown
  label="Monthly recurring revenue"
  delta={0.064}
  deltaLabel="vs September"
  data={data}
  name="plan"
  value="mrr"
  format="currency:USD"
  show="share"
  note="Illustrative data"
  style={{ maxWidth: 420 }}
/>
```

#### Hero, sorted

```tsx
import { MetricBreakdown } from "insightcharts";

const data = [
  { party: "Conservative", seats: 121 },
  { party: "Labour", seats: 411 },
  { party: "Liberal Democrat", seats: 72 },
  { party: "SNP", seats: 9 },
  { party: "Others", seats: 37 },
];

<MetricBreakdown
  size="hero"
  sort="desc"
  label="Seats in the House of Commons, 2024"
  data={data}
  name="party"
  value="seats"
  source="House of Commons Library"
  note="Figures are approximate, for illustration"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/metric-breakdown.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/metric-breakdown.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Poster (`poster`)

> 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.

- Component: `Poster` (import from `insightcharts`)
- Spec type: `"poster"`
- Level: molecule. Category: poster.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it as the outer frame of any infographic: one dominant graphic with a few supporting panels, on a painted ground. Give it a poster theme (`noir`, `magenta`, `dusk`, `paper`, `ocean`, `forest`, `blueprint`, `sunrise`) and put a chart or figure spec in each panel. Put the one fact in `title` and keep panel headings short. It reflows to one column under 600px.

### Avoid

Long reading text or more than about six panels (use `report-page` or `visual-essay`). A single fact at a fixed social size (use `social-card`). Charts that need axes, gridlines and dense labels to be read, because a poster ground suits large flat marks with their values printed on them.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/poster
```

The file lands at `components/insightcharts/molecules/poster.tsx`. `@insightcharts/poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, BigNumber, DonutChart, PictogramChart, Poster } from "insightcharts";

<Poster
  theme="noir"
  kicker="Transport"
  title="Riverton's bike-share scheme carried 4.2 million trips in 2025"
  subtitle="Trips, bikes and reasons for riding in the city's public bike-share scheme, January to December 2025."
  panels={[
    {
      span: 4,
      valign: "center",
      content: <BigNumber
        size="hero"
        value="4.2 million"
        label="Trips in 2025"
        context="3.4 million in 2024"
      />,
    },
    {
      span: 8,
      title: "Old Town had 1,150 of the scheme's 3,000 bikes",
      content: <PictogramChart
        data={[
          { district: "Old Town", bikes: 1150 },
          { district: "Harbour", bikes: 820 },
          { district: "University", bikes: 640 },
          { district: "Northside", bikes: 390 },
        ]}
        name="district"
        value="bikes"
        unit={50}
        unitLabel="50 bikes"
        icon="bike"
        highlight="Old Town"
      />,
      source: "Riverton Transport Office",
    },
    {
      span: 7,
      title: "670,000 trips were made on Wednesdays in 2025",
      subtitle: "Trips by day of the week, thousands, 2025",
      content: <BarChart
        data={[
          { day: "Mon", trips: 610 },
          { day: "Tue", trips: 655 },
          { day: "Wed", trips: 670 },
          { day: "Thu", trips: 662 },
          { day: "Fri", trips: 640 },
          { day: "Sat", trips: 520 },
          { day: "Sun", trips: 443 },
        ]}
        x="day"
        y="trips"
        orientation="vertical"
        sort="none"
        highlight="Wed"
        format="{value}k"
        height={260}
      />,
    },
    {
      span: 5,
      title: "46% of trips were commutes",
      subtitle: "Share of trips by stated purpose, rider survey, 2025",
      content: <DonutChart
        data={[
          { purpose: "Commuting", share: 46 },
          { purpose: "Leisure", share: 27 },
          { purpose: "Errands", share: 18 },
          { purpose: "Other", share: 9 },
        ]}
        name="purpose"
        value="share"
        format="{value}%"
        centerValue="46%"
        centerLabel="Commuting"
        height={260}
      />,
    },
  ]}
  sources={["Riverton Transport Office", "Riverton rider survey 2025"]}
  note="Riverton is an invented city. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "poster",
  "theme": "noir",
  "kicker": "Transport",
  "title": "Riverton's bike-share scheme carried 4.2 million trips in 2025",
  "subtitle": "Trips, bikes and reasons for riding in the city's public bike-share scheme, January to December 2025.",
  "panels": [
    {
      "span": 4,
      "valign": "center",
      "content": {
        "type": "big-number",
        "size": "hero",
        "value": "4.2 million",
        "label": "Trips in 2025",
        "context": "3.4 million in 2024"
      }
    },
    {
      "span": 8,
      "title": "Old Town had 1,150 of the scheme's 3,000 bikes",
      "content": {
        "type": "pictogram-chart",
        "data": [
          { "district": "Old Town", "bikes": 1150 },
          { "district": "Harbour", "bikes": 820 },
          { "district": "University", "bikes": 640 },
          { "district": "Northside", "bikes": 390 }
        ],
        "name": "district",
        "value": "bikes",
        "unit": 50,
        "unitLabel": "50 bikes",
        "icon": "bike",
        "highlight": "Old Town"
      },
      "source": "Riverton Transport Office"
    },
    {
      "span": 7,
      "title": "670,000 trips were made on Wednesdays in 2025",
      "subtitle": "Trips by day of the week, thousands, 2025",
      "content": {
        "type": "bar-chart",
        "data": [
          { "day": "Mon", "trips": 610 },
          { "day": "Tue", "trips": 655 },
          { "day": "Wed", "trips": 670 },
          { "day": "Thu", "trips": 662 },
          { "day": "Fri", "trips": 640 },
          { "day": "Sat", "trips": 520 },
          { "day": "Sun", "trips": 443 }
        ],
        "x": "day",
        "y": "trips",
        "orientation": "vertical",
        "sort": "none",
        "highlight": "Wed",
        "format": "{value}k",
        "height": 260
      }
    },
    {
      "span": 5,
      "title": "46% of trips were commutes",
      "subtitle": "Share of trips by stated purpose, rider survey, 2025",
      "content": {
        "type": "donut-chart",
        "data": [
          { "purpose": "Commuting", "share": 46 },
          { "purpose": "Leisure", "share": 27 },
          { "purpose": "Errands", "share": 18 },
          { "purpose": "Other", "share": 9 }
        ],
        "name": "purpose",
        "value": "share",
        "format": "{value}%",
        "centerValue": "46%",
        "centerLabel": "Commuting",
        "height": 260
      }
    }
  ],
  "sources": ["Riverton Transport Office", "Riverton rider survey 2025"],
  "note": "Riverton is an invented city. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | The poster's one fact, as a plain sentence with its number. Set large and light in the theme's display face. |
| `kicker` | `string` |  | Small label above the title: the topic or series. |
| `subtitle` | `string` |  | One or two lines under the title: the measure, population and period. |
| `panels` (required) | `PosterPanel[]` |  | The blocks, in reading order. Each is `{ content, title?, subtitle?, span?, rowSpan?, source?, note?, align?, valign?, bleed?, id? }`. `content` is a component spec or rendered content. `span` is in units of `columns` (default: full width). `bleed` runs the content to the poster's left and right edges. |
| `columns` | `number` | `12` | Columns of the layout grid: a 12-unit grid, or a simple count such as 2 or 3. Under 600px every panel is full width; from 600 to 760px the grid has two columns. |
| `gap` | `number` |  | Space between panels in px. Default 40 (28 under 600px). |
| `padding` | `number` |  | Space between the poster's edge and its content in px. Default 56 (36 under 900px, 20 under 600px). |
| `maxWidth` | `number \| string` | `1200` | Widest the poster is drawn. It is centred in wider containers. |
| `aspect` | `number \| string` |  | Fixed shape as width / height: `0.75`, `"3:4"`, `"16:9"`. The poster still grows when its content needs more height, and the ratio is dropped under 600px. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"noir"` | A poster theme name, any other theme name, or a theme object. It is passed on to everything inside. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `background` | `string` |  | CSS background of the sheet, a colour or a gradient. Default: the poster theme's ground. Keep it close to the theme's `surface`, which charts use for the gaps between marks. |
| `rules` | `"none" \| "solid" \| "dotted"` | `"dotted"` | Lines under the masthead, between rows of panels and above the footer. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `titleAlign` | `"left" \| "center"` | `"left"` | Alignment of the masthead. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster. The image is the whole sheet, drawn from the DOM onto a canvas, without the control. |
| `exportWidth` | `number` | `2400` | Width of the downloaded PNG in pixels. |
| `filename` | `string` |  | File name without extension. Defaults to a slug of the title. |
| `downloadLabel` | `string` | `"Download PNG"` | Label of the download control. |
| `onExport` | `(blob: Blob) => void` |  | Called with the PNG after a download. |

### Composition

- Composes: [big-number](https://insightcharts.dev/llms/big-number.md), [pictogram-chart](https://insightcharts.dev/llms/pictogram-chart.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [donut-chart](https://insightcharts.dev/llms/donut-chart.md), [treemap](https://insightcharts.dev/llms/treemap.md), [waffle-chart](https://insightcharts.dev/llms/waffle-chart.md), [segmented-bar](https://insightcharts.dev/llms/segmented-bar.md), [icon-stat](https://insightcharts.dev/llms/icon-stat.md)
- Used by: [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md), [count-poster](https://insightcharts.dev/llms/count-poster.md), [flow-poster](https://insightcharts.dev/llms/flow-poster.md), [matrix-poster](https://insightcharts.dev/llms/matrix-poster.md), [network-poster](https://insightcharts.dev/llms/network-poster.md), [profile-poster](https://insightcharts.dev/llms/profile-poster.md), [radial-poster](https://insightcharts.dev/llms/radial-poster.md), [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md), [scale-poster](https://insightcharts.dev/llms/scale-poster.md), [timeline-poster](https://insightcharts.dev/llms/timeline-poster.md)

### More examples

#### Magenta, one dominant graphic, with download

```tsx
import { BigNumber, Poster, Treemap, WaffleChart } from "insightcharts";

<Poster
  theme="magenta"
  kicker="Food"
  title="Households in Norland threw away 61 kg of food per person in 2025"
  subtitle="Food thrown away at home, kilograms per person, by type of food."
  download
  panels={[
    {
      content: <Treemap
        data={[
          { food: "Vegetables", kg: 14.2 },
          { food: "Bread and bakery", kg: 11.5 },
          { food: "Fruit", kg: 9.8 },
          { food: "Dairy and eggs", kg: 8.1 },
          { food: "Cooked leftovers", kg: 7.6 },
          { food: "Meat and fish", kg: 5.3 },
          { food: "Drinks", kg: 2.7 },
          { food: "Other", kg: 1.8 },
        ]}
        name="food"
        value="kg"
        format="{value} kg"
        height={420}
      />,
      source: "Norland Waste Agency household survey",
    },
    {
      span: 6,
      title: "64% of the food thrown away could have been eaten",
      subtitle: "Each square is 1% of the weight thrown away",
      content: <WaffleChart
        data={[{ group: "Could have been eaten", share: 64 }]}
        name="group"
        value="share"
        total={100}
        restLabel="Peel, bones and shells"
        rows={5}
        height={190}
      />,
    },
    {
      span: 6,
      valign: "center",
      content: <BigNumber
        size="hero"
        value="€412"
        label="Cost of the food one household threw away in 2025"
        context="€388 in 2024"
      />,
    },
  ]}
  sources="Norland Waste Agency"
  note="Norland is an invented country. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Dusk, gradient ground, fixed 4:5 shape

```tsx
import { BarChart, BigNumber, PictogramChart, Poster } from "insightcharts";

<Poster
  theme="dusk"
  aspect="4:5"
  maxWidth={820}
  columns={2}
  kicker="Energy"
  title="Solar supplied 31% of Port Alba's electricity in 2025"
  panels={[
    {
      span: 2,
      title: "Solar generated 3.1 TWh of the island's 10 TWh",
      content: <PictogramChart
        data={[
          { source: "Solar", twh: 3.1 },
          { source: "Wind", twh: 2.6 },
          { source: "Gas", twh: 2.9 },
          { source: "Hydro", twh: 1.4 },
        ]}
        name="source"
        value="twh"
        unit={0.2}
        unitLabel="0.2 TWh"
        icons={{ Solar: "solar-panel", Wind: "wind-turbine", Gas: "flame", Hydro: "drop" }}
        icon="bolt"
        highlight="Solar"
        format="{value} TWh"
      />,
    },
    {
      span: 2,
      title: "Solar's share was 51% in July and 8% in December",
      subtitle: "Solar share of electricity generated, by month, 2025",
      content: <BarChart
        data={[
          { month: "Jan", share: 9 },
          { month: "Feb", share: 14 },
          { month: "Mar", share: 24 },
          { month: "Apr", share: 35 },
          { month: "May", share: 44 },
          { month: "Jun", share: 49 },
          { month: "Jul", share: 51 },
          { month: "Aug", share: 46 },
          { month: "Sep", share: 36 },
          { month: "Oct", share: 24 },
          { month: "Nov", share: 13 },
          { month: "Dec", share: 8 },
        ]}
        x="month"
        y="share"
        orientation="vertical"
        sort="none"
        highlight="Jul"
        format="{value}%"
        height={240}
      />,
    },
    {
      span: 1,
      content: <BigNumber size="hero" value="31%" label="Solar share of electricity in 2025" />,
    },
    {
      span: 1,
      content: <BigNumber size="hero" value="12%" label="Solar share of electricity in 2020" />,
    },
  ]}
  sources="Port Alba Grid Operator"
  note="Port Alba is an invented island. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Paper, three columns, solid rules, centred masthead

```tsx
import { BigNumber, IconStat, Poster, SegmentedBar } from "insightcharts";

<Poster
  theme="paper"
  columns={3}
  rules="solid"
  titleAlign="center"
  kicker="Libraries"
  title="Hollin Valley's libraries lent 318,000 items in 2025"
  subtitle="Loans from the valley's six public libraries, January to December 2025."
  panels={[
    {
      span: 2,
      title: "Printed books were 171,000 of the 318,000 loans",
      subtitle: "Loans by type of item, thousands",
      content: <SegmentedBar
        data={[
          { kind: "Printed books", items: 171 },
          { kind: "E-books", items: 74 },
          { kind: "Audiobooks", items: 48 },
          { kind: "Films and music", items: 25 },
        ]}
        name="kind"
        value="items"
        format="{value}k"
      />,
      source: "Hollin Valley Library Service",
    },
    {
      span: 1,
      valign: "center",
      content: <BigNumber size="hero" value="318,000" label="Items lent in 2025" context="301,000 in 2024" />,
    },
    {
      span: 3,
      content: <IconStat
        icon="book"
        count={3}
        total={10}
        value="3 in 10"
        text="residents borrowed at least one item in 2025."
      />,
    },
  ]}
  sources="Hollin Valley Library Service annual return"
  note="Hollin Valley is an invented place. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Proportion statement (`proportion-statement`)

> A 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.

- Component: `ProportionStatement` (import from `insightcharts`)
- Spec type: `"proportion-statement"`
- Level: molecule. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

One proportion that is easier to read as a count of people or units than as a percentage. Round to a small whole first: 1 in 4 with icons, 37 in every 100 with a waffle.

### Avoid

Several shares side by side (use `bar-chart`, or `waffle-chart` with categories); a precise percentage where the decimals matter (use `big-number`); totals above 100.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/proportion-statement
```

The file lands at `components/insightcharts/molecules/proportion-statement.tsx`. `@insightcharts/proportion-statement-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ProportionStatement } from "insightcharts";

<ProportionStatement
  value={33}
  total={100}
  text="people in the world have never used the internet."
  detail="That was about 2.6 billion people in 2023."
  source="ITU Facts and Figures 2023"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "proportion-statement",
  "value": 33,
  "total": 100,
  "text": "people in the world have never used the internet.",
  "detail": "That was about 2.6 billion people in 2023.",
  "source": "ITU Facts and Figures 2023",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` (required) | `number` |  | How many of the whole are counted. |
| `total` | `number` | `100` | The whole. |
| `figure` | `string` |  | The emphasised words. Default: "{value} in every {total}", or "{value} in {total}" up to 20. |
| `text` (required) | `string` |  | The rest of the sentence, read straight after the figure. |
| `visual` | `"waffle" \| "icons"` |  | Grid of cells or row of glyphs. Default: icons up to a total of 20, waffle above. |
| `icon` | `"circle" \| "person" \| "square"` | `"person"` | Glyph for the `icons` visual. |
| `shape` | `"square" \| "circle"` | `"square"` | Cell shape for the `waffle` visual. |
| `side` | `"left" \| "right"` | `"left"` | Side the visual sits on; under 520px it goes on top. |
| `detail` | `string` |  | A second, quieter sentence under the statement. |
| `source` | `string` |  | Shown under the statement as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the visual. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [waffle-chart](https://insightcharts.dev/llms/waffle-chart.md), [icon-stat](https://insightcharts.dev/llms/icon-stat.md)
- Used by: [explainer](https://insightcharts.dev/llms/explainer.md)

### More examples

#### Icons, 1 in 4

```tsx
import { ProportionStatement } from "insightcharts";

<ProportionStatement
  value={1}
  total={4}
  text="households could not cover an unexpected bill of €500 without borrowing."
  source="Eurostat, EU-SILC 2023"
  note="Figures are approximate, for illustration"
/>
```

#### Icons on the right, custom figure

```tsx
import { ProportionStatement } from "insightcharts";

<ProportionStatement
  value={9}
  total={10}
  figure="Nine in ten"
  icon="circle"
  side="right"
  text="new cars sold in Norway in 2024 were fully electric."
  detail="Battery-electric models were 89% of registrations in 2024. They were 82% in 2023."
  source="Norwegian Road Federation (OFV)"
  note="Figures are approximate, for illustration"
/>
```

#### Waffle with circles

```tsx
import { ProportionStatement } from "insightcharts";

<ProportionStatement
  value={12}
  total={100}
  shape="circle"
  text="adults in the survey had changed jobs in the past year."
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/proportion-statement.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/proportion-statement.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Quote with figure (`quote-figure`)

> A pull-quote paired with the statistic or small chart that backs it up, side by side and stacking in narrow containers.

- Component: `QuoteFigure` (import from `insightcharts`)
- Spec type: `"quote-figure"`
- Level: molecule. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

A quotation shown next to the number it refers to: an interview finding with its survey figure, an executive's statement with the metric. One per section.

### Avoid

A quote with no evidence (use `pull-quote`); a figure that needs axes to read (use `chart-callout` and put the quote in prose); unattributed quotations.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/quote-figure
```

The file lands at `components/insightcharts/molecules/quote-figure.tsx`. `@insightcharts/quote-figure-demo` adds a ready-made example next to it.

### Usage

```tsx
import { QuoteFigure, Sparkline } from "insightcharts";

<QuoteFigure
  quote="Solar met more than half of demand on 41% of summer afternoons in 2024. We do not have enough storage for the midday surplus yet."
  attribution="Marta Keller"
  role="Grid planner, quoted in the 2024 system adequacy review"
  stat={{
    value: 0.41,
    format: "percent",
    label: "Summer afternoons when solar met over half of demand",
    context: "It was 6% of afternoons in 2019",
  }}
  figure={<Sparkline
    data={[
      { year: "2019", share: 6 },
      { year: "2020", share: 9 },
      { year: "2021", share: 14 },
      { year: "2022", share: 22 },
      { year: "2023", share: 31 },
      { year: "2024", share: 41 },
    ]}
    x="year"
    y="share"
    format="{value}%"
    area
  />}
  source="National grid operator, hourly generation data"
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "quote-figure",
  "quote": "Solar met more than half of demand on 41% of summer afternoons in 2024. We do not have enough storage for the midday surplus yet.",
  "attribution": "Marta Keller",
  "role": "Grid planner, quoted in the 2024 system adequacy review",
  "stat": {
    "value": 0.41,
    "format": "percent",
    "label": "Summer afternoons when solar met over half of demand",
    "context": "It was 6% of afternoons in 2019"
  },
  "figure": {
    "type": "sparkline",
    "data": [
      { "year": "2019", "share": 6 },
      { "year": "2020", "share": 9 },
      { "year": "2021", "share": 14 },
      { "year": "2022", "share": 22 },
      { "year": "2023", "share": 31 },
      { "year": "2024", "share": 41 }
    ],
    "x": "year",
    "y": "share",
    "format": "{value}%",
    "area": true
  },
  "source": "National grid operator, hourly generation data",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `quote` (required) | `string` |  | The words quoted, without quotation marks. |
| `attribution` | `string` |  | Who said it. |
| `role` | `string` |  | Their role, or where it was said. |
| `cite` | `string` |  | Source URL, linked from the attribution. |
| `stat` | `{ value, label, context?, delta?, deltaLabel?, upIsGood?, format? }` |  | The statistic that backs the quote up; takes the props of `big-number`. |
| `figure` | `Slot` |  | A small chart or figure instead of, or under, the statistic: a spec or a React element. |
| `side` | `"left" \| "right"` | `"right"` | Side the evidence sits on; under 640px it goes underneath. |
| `source` | `string` |  | Shown underneath as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the quote and the figure. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [pull-quote](https://insightcharts.dev/llms/pull-quote.md), [big-number](https://insightcharts.dev/llms/big-number.md), [sparkline](https://insightcharts.dev/llms/sparkline.md)
- Used by: no molecule or template yet

### More examples

#### Evidence on the left, statistic only

```tsx
import { QuoteFigure } from "insightcharts";

<QuoteFigure
  side="left"
  quote="Most of the customers who left told us they stopped at the second screen of setup."
  attribution="Dana Whitfield"
  role="Head of customer research"
  stat={{
    value: 0.58,
    format: "percent",
    label: "Churned accounts that never finished setup",
    delta: "−21 pts",
    deltaLabel: "after the redesign",
    upIsGood: false,
  }}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/quote-figure.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/quote-figure.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Ranked list (`ranked-list`)

> A ranking as a list: position, name, value and a thin in-row bar, with an optional change indicator and highlighted rows.

- Component: `RankedList` (import from `insightcharts`)
- Spec type: `"ranked-list"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

A top-N list where the names matter as much as the values: league tables, best and worst performers, leaderboards with a movement column. It keeps long names readable and works in a narrow column.

### Avoid

Precise visual comparison of many values or more than about 15 rows (use `bar-chart`); several measures per entity (use `data-table` or `comparison-table`); rank changing over time (use `bump-chart`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/ranked-list
```

The file lands at `components/insightcharts/molecules/ranked-list.tsx`. `@insightcharts/ranked-list-demo` adds a ready-made example next to it.

### Usage

```tsx
import { RankedList } from "insightcharts";

const data = [
  { city: "Copenhagen", country: "Denmark", share: 49, change: 0.04 },
  { city: "Amsterdam", country: "Netherlands", share: 35, change: 0.01 },
  { city: "Utrecht", country: "Netherlands", share: 34, change: 0.02 },
  { city: "Münster", country: "Germany", share: 31, change: 0 },
  { city: "Antwerp", country: "Belgium", share: 26, change: 0.05 },
  { city: "Malmö", country: "Sweden", share: 25, change: -0.01 },
  { city: "Bordeaux", country: "France", share: 13, change: 0.06 },
  { city: "Paris", country: "France", share: 11, change: 0.07 },
];

<RankedList
  title="11% of commuting trips in Paris are made by bicycle"
  subtitle="Share of commuting trips made by bicycle, selected European cities, with change since 2019"
  data={data}
  name="city"
  detail="country"
  value="share"
  format="{value}%"
  change="change"
  highlight="Paris"
  source="City mobility surveys"
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "ranked-list",
  "title": "11% of commuting trips in Paris are made by bicycle",
  "subtitle": "Share of commuting trips made by bicycle, selected European cities, with change since 2019",
  "data": [
    { "city": "Copenhagen", "country": "Denmark", "share": 49, "change": 0.04 },
    { "city": "Amsterdam", "country": "Netherlands", "share": 35, "change": 0.01 },
    { "city": "Utrecht", "country": "Netherlands", "share": 34, "change": 0.02 },
    { "city": "Münster", "country": "Germany", "share": 31, "change": 0 },
    { "city": "Antwerp", "country": "Belgium", "share": 26, "change": 0.05 },
    { "city": "Malmö", "country": "Sweden", "share": 25, "change": -0.01 },
    { "city": "Bordeaux", "country": "France", "share": 13, "change": 0.06 },
    { "city": "Paris", "country": "France", "share": 11, "change": 0.07 }
  ],
  "name": "city",
  "detail": "country",
  "value": "share",
  "format": "{value}%",
  "change": "change",
  "highlight": "Paris",
  "source": "City mobility surveys",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `DataInput` |  | One row per entity. Omit inside `<InsightData>`. |
| `transform` | `Transform \| Transform[]` |  | Applied before ranking. |
| `name` (required) | `string` |  | Field naming each entity. |
| `value` (required) | `string` |  | Field with the value that ranks them. Bars start at zero. |
| `change` | `string` |  | Field with a change shown at the end of each row: a number (0.12 is +12%) or a string. |
| `changeFormat` | `FormatSpec` | `signed percent` | Format for numeric changes, e.g. `"signed"` for places moved. |
| `upIsGood` | `boolean` | `true` | Whether a positive change is good news. |
| `detail` | `string` |  | Field with a short secondary line under each name. |
| `sort` | `"desc" \| "asc" \| "none"` | `"desc"` | Order by value; `none` keeps the data order. |
| `limit` | `number` |  | Show only the first N rows after sorting. |
| `highlight` | `string \| string[]` |  | Entity names to emphasise. The other bars are drawn in grey. |
| `bar` | `boolean` | `true` | Draw the in-row bar. |
| `max` | `number` |  | Value at which a bar is full. Default: the largest value shown. |
| `format` | `FormatSpec` | `"auto"` | Number format for the values. |
| `title` | `string` |  | The main fact with its number, or a plain label. |
| `subtitle` | `string` |  | Measure, population and period. |
| `source` | `string` |  | Shown under the list as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [delta](https://insightcharts.dev/llms/delta.md)
- Used by: [scorecard](https://insightcharts.dev/llms/scorecard.md)

### More examples

#### Top five, no highlight

```tsx
import { RankedList } from "insightcharts";

const data = [
  { city: "Copenhagen", country: "Denmark", share: 49, change: 0.04 },
  { city: "Amsterdam", country: "Netherlands", share: 35, change: 0.01 },
  { city: "Utrecht", country: "Netherlands", share: 34, change: 0.02 },
  { city: "Münster", country: "Germany", share: 31, change: 0 },
  { city: "Antwerp", country: "Belgium", share: 26, change: 0.05 },
  { city: "Malmö", country: "Sweden", share: 25, change: -0.01 },
  { city: "Bordeaux", country: "France", share: 13, change: 0.06 },
  { city: "Paris", country: "France", share: 11, change: 0.07 },
];

<RankedList
  data={data}
  name="city"
  value="share"
  format="{value}%"
  limit={5}
  title="49% of commuting trips in Copenhagen are made by bicycle"
/>
```

#### Places moved, long names, no bar

```tsx
import { RankedList } from "insightcharts";

const data = [
  { name: "Erasmus University Medical Center Rotterdam", score: 94.1, moved: 2 },
  { name: "Karolinska University Hospital", score: 93.6, moved: -1 },
  { name: "Amsterdam University Medical Centers", score: 92.8, moved: 0 },
  { name: "Charité – Universitätsmedizin Berlin", score: 91.9, moved: -1 },
  { name: "University Medical Center Utrecht", score: 90.4, moved: 3 },
];

<RankedList
  title="Three of the top five hospitals are in the Netherlands"
  data={data}
  name="name"
  value="score"
  change="moved"
  changeFormat="signed"
  bar={false}
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/ranked-list.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/ranked-list.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Scrolly chart (`scrolly-chart`)

> A scroll-driven story from JSON: one base chart spec and a list of steps, each with narration and a patch of chart props applied while that step is active.

- Component: `ScrollyChart` (import from `insightcharts`)
- Spec type: `"scrolly-chart"`
- Level: molecule. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Walking a reader through one chart in stages: show everything, highlight the subject, change the measure, add the annotation. Make ONE change per step (the highlight, the data or the encoding) so the reader can see what changed.

### Avoid

Steps that change several things at once, or that swap to an unrelated chart (start a new `section` instead). More than about seven steps. A fact that one view can show (use `chart-callout`). In documents that will be printed or embedded in a short frame, set `scrollMode: "steps"`.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/scrolly-chart
```

The file lands at `components/insightcharts/molecules/scrolly-chart.tsx`. `@insightcharts/scrolly-chart-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, ScrollyChart, registerComponents } from "insightcharts";

// Specs passed as data are resolved by name when rendered.
registerComponents({ BarChart });

<ScrollyChart
  chart={{
    type: "bar-chart",
    data: [
      { source: "Coal", y2015: 24.6, y2024: 9.8 },
      { source: "Gas", y2015: 15.8, y2024: 15.7 },
      { source: "Nuclear", y2015: 27.1, y2024: 23.7 },
      { source: "Wind", y2015: 9.2, y2024: 17.4 },
      { source: "Hydro", y2015: 12, y2024: 13.2 },
      { source: "Solar", y2015: 2.9, y2024: 11.1 },
    ],
    x: "source",
    y: "y2015",
    sort: "none",
    orientation: "horizontal",
    format: "{value}%",
    height: 300,
    title: "EU electricity generation by source, 2015",
    subtitle: "Share of EU electricity generation, %",
    source: "Ember, European Electricity Review 2025",
    note: "Rounded, approximate figures for illustration",
  }}
  steps={[
    {
      id: "baseline",
      label: "2015",
      content: "In 2015 **nuclear and coal** together supplied 51.7% of the EU's electricity.",
    },
    {
      id: "coal",
      content: "Coal supplied 24.6% in 2015. Only nuclear supplied more.",
      highlight: "Coal",
    },
    {
      id: "today",
      label: "2024",
      content: "In 2024 coal supplied 9.8%.",
      highlight: "Coal",
      y: "y2024",
      title: "EU electricity generation by source, 2024",
    },
    {
      id: "solar",
      content: "**Solar** supplied 11.1% in 2024. It supplied 2.9% in 2015.",
      highlight: "Solar",
      y: "y2024",
      title: "Solar supplied 11.1% of EU electricity in 2024",
    },
  ]}
  stepHeight="70vh"
  stickyTop={16}
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "scrolly-chart",
  "chart": {
    "type": "bar-chart",
    "data": [
      { "source": "Coal", "y2015": 24.6, "y2024": 9.8 },
      { "source": "Gas", "y2015": 15.8, "y2024": 15.7 },
      { "source": "Nuclear", "y2015": 27.1, "y2024": 23.7 },
      { "source": "Wind", "y2015": 9.2, "y2024": 17.4 },
      { "source": "Hydro", "y2015": 12, "y2024": 13.2 },
      { "source": "Solar", "y2015": 2.9, "y2024": 11.1 }
    ],
    "x": "source",
    "y": "y2015",
    "sort": "none",
    "orientation": "horizontal",
    "format": "{value}%",
    "height": 300,
    "title": "EU electricity generation by source, 2015",
    "subtitle": "Share of EU electricity generation, %",
    "source": "Ember, European Electricity Review 2025",
    "note": "Rounded, approximate figures for illustration"
  },
  "steps": [
    {
      "id": "baseline",
      "label": "2015",
      "content": "In 2015 **nuclear and coal** together supplied 51.7% of the EU's electricity."
    },
    {
      "id": "coal",
      "content": "Coal supplied 24.6% in 2015. Only nuclear supplied more.",
      "highlight": "Coal"
    },
    {
      "id": "today",
      "label": "2024",
      "content": "In 2024 coal supplied 9.8%.",
      "highlight": "Coal",
      "y": "y2024",
      "title": "EU electricity generation by source, 2024"
    },
    {
      "id": "solar",
      "content": "**Solar** supplied 11.1% in 2024. It supplied 2.9% in 2015.",
      "highlight": "Solar",
      "y": "y2024",
      "title": "Solar supplied 11.1% of EU electricity in 2024"
    }
  ],
  "stepHeight": "70vh",
  "stickyTop": 16
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `chart` (required) | `InsightSpec` |  | The base chart spec: `{ type, data, x, y, ... }`. Give it a `title`; steps may replace it. |
| `steps` (required) | `{ content, id?, label?, ...chart props }[]` |  | The steps in order. `content` is a short paragraph that says plainly what the chart now shows (`**bold**` works). Every other key is a chart prop merged over `chart` for that step: `highlight`, `transform`, `annotations`, `x`, `y`, `title`… Use `null` to remove a base prop. Change one thing per step. |
| `cumulative` | `boolean` | `false` | Each step's patch builds on the previous steps instead of on the base spec alone. |
| `scrollMode` | `"auto" \| "scroll" \| "swipe" \| "steps"` | `"auto"` | `scroll` pins the chart while steps scroll past; `swipe` makes steps swipeable cards; `steps` shows previous/next buttons; `auto` uses scroll, or swipe on narrow touch screens. (Named `scrollMode` because `mode` is the colour mode.) |
| `side` | `"left" \| "right"` | `"left"` | Side of the text column in scroll mode. Narrow containers overlay the text on the chart. |
| `stickyTop` | `number \| string` | `0` | Offset from the top of the viewport at which the chart pins; set it to the height of a fixed header. |
| `stepHeight` | `string` | `"80vh"` | Scroll distance per step, as a CSS length. |
| `onStepChange` | `(index) => void` |  | Called when the active step changes. |
| `title` | `string` |  | Heading above the whole story. |
| `subtitle` | `string` |  | Line under the heading. |
| `source` | `string` |  | Shown after the last step as "Source: ...". Prefer the chart's own `source`, which stays visible. |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the chart and the step cards. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [prose](https://insightcharts.dev/llms/prose.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md)
- Used by: [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Steps mode (buttons), cumulative patches

```tsx
import { BarChart, ScrollyChart, registerComponents } from "insightcharts";

// Specs passed as data are resolved by name when rendered.
registerComponents({ BarChart });

<ScrollyChart
  scrollMode="steps"
  cumulative
  chart={{
    type: "bar-chart",
    data: [
      { source: "Coal", y2015: 24.6, y2024: 9.8 },
      { source: "Gas", y2015: 15.8, y2024: 15.7 },
      { source: "Nuclear", y2015: 27.1, y2024: 23.7 },
      { source: "Wind", y2015: 9.2, y2024: 17.4 },
      { source: "Hydro", y2015: 12, y2024: 13.2 },
      { source: "Solar", y2015: 2.9, y2024: 11.1 },
    ],
    x: "source",
    y: "y2015",
    sort: "none",
    orientation: "horizontal",
    format: "{value}%",
    height: 300,
    title: "EU electricity generation by source, 2015",
    subtitle: "Share of EU electricity generation, %",
    source: "Ember, European Electricity Review 2025",
    note: "Rounded, approximate figures for illustration",
  }}
  steps={[
    { content: "The chart shows each source's share in 2015." },
    { content: "**Coal** is highlighted. It supplied 24.6% in 2015.", highlight: "Coal" },
    {
      content: "The chart now shows 2024. Coal is still highlighted because the patches accumulate.",
      y: "y2024",
      title: "EU electricity generation by source, 2024",
    },
    {
      content: "The highlight is removed. The sources are sorted by their 2024 share.",
      highlight: null,
      sort: "desc",
    },
  ]}
/>
```

#### Swipe mode

```tsx
import { BarChart, ScrollyChart, registerComponents } from "insightcharts";

// Specs passed as data are resolved by name when rendered.
registerComponents({ BarChart });

<ScrollyChart
  scrollMode="swipe"
  chart={{
    type: "bar-chart",
    data: [
      { source: "Coal", y2015: 24.6, y2024: 9.8 },
      { source: "Gas", y2015: 15.8, y2024: 15.7 },
      { source: "Nuclear", y2015: 27.1, y2024: 23.7 },
      { source: "Wind", y2015: 9.2, y2024: 17.4 },
      { source: "Hydro", y2015: 12, y2024: 13.2 },
      { source: "Solar", y2015: 2.9, y2024: 11.1 },
    ],
    x: "source",
    y: "y2015",
    sort: "none",
    orientation: "horizontal",
    format: "{value}%",
    height: 300,
    title: "EU electricity generation by source, 2015",
    subtitle: "Share of EU electricity generation, %",
    source: "Ember, European Electricity Review 2025",
    note: "Rounded, approximate figures for illustration",
  }}
  steps={[
    {
      id: "baseline",
      label: "2015",
      content: "In 2015 **nuclear and coal** together supplied 51.7% of the EU's electricity.",
    },
    {
      id: "coal",
      content: "Coal supplied 24.6% in 2015. Only nuclear supplied more.",
      highlight: "Coal",
    },
    {
      id: "today",
      label: "2024",
      content: "In 2024 coal supplied 9.8%.",
      highlight: "Coal",
      y: "y2024",
      title: "EU electricity generation by source, 2024",
    },
    {
      id: "solar",
      content: "**Solar** supplied 11.1% in 2024. It supplied 2.9% in 2015.",
      highlight: "Solar",
      y: "y2024",
      title: "Solar supplied 11.1% of EU electricity in 2024",
    },
  ]}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/scrolly-chart.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/scrolly-chart.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Section (`section`)

> A story section: a numbered step marker or a headline, introductory prose, then one or more exhibits in a responsive one- to three-column grid.

- Component: `Section` (import from `insightcharts`)
- Spec type: `"section"`
- Level: molecule. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

The building block of a longer piece. Each section states one fact with its number in the title, explains it in a paragraph and shows it in one to three exhibits. Use `step` when the sections are read in order.

### Avoid

The opening of a piece (use `hero-figure`); a single chart with one callout (use `chart-callout` directly); more than three exhibits in one section (split it).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/section
```

The file lands at `components/insightcharts/molecules/section.tsx`. `@insightcharts/section-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, LineChart, Section } from "insightcharts";

<Section
  step={2}
  total={4}
  title="First-quarter churn was 2.0% for customers who joined after March"
  intro="Monthly churn fell from 4.2% in January to 2.1% in December 2024. The new onboarding launched in March. Customers who joined after March had first-quarter churn of **2.0%**. Customers who joined before March had 4.1%."
  columns={2}
  body={[
    <LineChart
      data={[
        { month: "2024-01-01", rate: 4.2 },
        { month: "2024-02-01", rate: 4.3 },
        { month: "2024-03-01", rate: 4.1 },
        { month: "2024-04-01", rate: 3.6 },
        { month: "2024-05-01", rate: 3.1 },
        { month: "2024-06-01", rate: 2.9 },
        { month: "2024-07-01", rate: 2.6 },
        { month: "2024-08-01", rate: 2.4 },
        { month: "2024-09-01", rate: 2.3 },
        { month: "2024-10-01", rate: 2.2 },
        { month: "2024-11-01", rate: 2.1 },
        { month: "2024-12-01", rate: 2.1 },
      ]}
      x="month"
      y="rate"
      format="{value}%"
      zero
      height={240}
      title="Monthly churn fell from 4.2% to 2.1% in 2024"
      subtitle="Monthly customer churn, 2024"
      annotations={[{ type: "line", axis: "x", value: "2024-03-01", label: "New onboarding" }]}
    />,
    <BarChart
      data={[{ cohort: "Before March", churn: 4.1 }, { cohort: "After March", churn: 2 }]}
      x="cohort"
      y="churn"
      format="{value}%"
      height={240}
      highlight="After March"
      title="First-quarter churn was 4.1% for customers who joined before March"
      subtitle="First-quarter churn by sign-up cohort, 2024"
    />,
  ]}
  outro="The next section covers the first 90 days after sign-up."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "section",
  "step": 2,
  "total": 4,
  "title": "First-quarter churn was 2.0% for customers who joined after March",
  "intro": "Monthly churn fell from 4.2% in January to 2.1% in December 2024. The new onboarding launched in March. Customers who joined after March had first-quarter churn of **2.0%**. Customers who joined before March had 4.1%.",
  "columns": 2,
  "body": [
    {
      "type": "line-chart",
      "data": [
        { "month": "2024-01-01", "rate": 4.2 },
        { "month": "2024-02-01", "rate": 4.3 },
        { "month": "2024-03-01", "rate": 4.1 },
        { "month": "2024-04-01", "rate": 3.6 },
        { "month": "2024-05-01", "rate": 3.1 },
        { "month": "2024-06-01", "rate": 2.9 },
        { "month": "2024-07-01", "rate": 2.6 },
        { "month": "2024-08-01", "rate": 2.4 },
        { "month": "2024-09-01", "rate": 2.3 },
        { "month": "2024-10-01", "rate": 2.2 },
        { "month": "2024-11-01", "rate": 2.1 },
        { "month": "2024-12-01", "rate": 2.1 }
      ],
      "x": "month",
      "y": "rate",
      "format": "{value}%",
      "zero": true,
      "height": 240,
      "title": "Monthly churn fell from 4.2% to 2.1% in 2024",
      "subtitle": "Monthly customer churn, 2024",
      "annotations": [{ "type": "line", "axis": "x", "value": "2024-03-01", "label": "New onboarding" }]
    },
    {
      "type": "bar-chart",
      "data": [{ "cohort": "Before March", "churn": 4.1 }, { "cohort": "After March", "churn": 2 }],
      "x": "cohort",
      "y": "churn",
      "format": "{value}%",
      "height": 240,
      "highlight": "After March",
      "title": "First-quarter churn was 4.1% for customers who joined before March",
      "subtitle": "First-quarter churn by sign-up cohort, 2024"
    }
  ],
  "outro": "The next section covers the first 90 days after sign-up."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | The section's main fact, as one plain sentence with its number. |
| `step` | `number \| string` |  | Step number: turns the heading into a numbered chapter marker ("02 — ..."). |
| `total` | `number` |  | Total steps, shown as "02 / 05". |
| `kicker` | `string` |  | Small label above an unnumbered heading. |
| `deck` | `string` |  | One plain sentence under the heading that adds a second fact. |
| `intro` | `string \| string[]` |  | Introductory narration. Supports `**bold**`, `*italic*` and links. |
| `body` | `Slot \| Slot[]` |  | The exhibits: one slot or several, each a spec or a React element. |
| `columns` | `1 \| 2 \| 3` | `1` | Columns for the body at full width; reduced under 720px and 520px. |
| `outro` | `string \| string[]` |  | Closing narration under the body. |
| `rule` | `boolean` | `false` | Hairline above the section. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading level. |
| `id` | `string` |  | Anchor id for deep links. |
| `spacing` | `"compact" \| "comfortable"` | `"comfortable"` | Vertical rhythm between heading, intro and body. |
| `children` | `ReactNode` |  | JSX alternative to `body`; each child becomes a grid item. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [step-marker](https://insightcharts.dev/llms/step-marker.md), [headline](https://insightcharts.dev/llms/headline.md), [prose](https://insightcharts.dev/llms/prose.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [stat-tile](https://insightcharts.dev/llms/stat-tile.md)
- Used by: no molecule or template yet

### More examples

#### Unnumbered, one exhibit, with a rule

```tsx
import { LineChart, Section } from "insightcharts";

<Section
  rule
  kicker="Retention"
  title="Monthly churn was between 2.1% and 2.4% from August to December 2024"
  deck="It was 4.2% in January."
  body={<LineChart
    data={[
      { month: "2024-01-01", rate: 4.2 },
      { month: "2024-02-01", rate: 4.3 },
      { month: "2024-03-01", rate: 4.1 },
      { month: "2024-04-01", rate: 3.6 },
      { month: "2024-05-01", rate: 3.1 },
      { month: "2024-06-01", rate: 2.9 },
      { month: "2024-07-01", rate: 2.6 },
      { month: "2024-08-01", rate: 2.4 },
      { month: "2024-09-01", rate: 2.3 },
      { month: "2024-10-01", rate: 2.2 },
      { month: "2024-11-01", rate: 2.1 },
      { month: "2024-12-01", rate: 2.1 },
    ]}
    x="month"
    y="rate"
    format="{value}%"
    zero
    height={260}
  />}
/>
```

#### Three columns of figures

```tsx
import { Section, StatTile } from "insightcharts";

<Section
  title="Product metrics, December 2024"
  columns={3}
  spacing="compact"
  body={[
    <StatTile
      label="Monthly churn"
      value="2.1%"
      delta="−2.1 pts"
      deltaLabel="vs January"
      upIsGood={false}
    />,
    <StatTile
      label="Monthly active users"
      value={48210}
      format="compact"
      delta={0.265}
      deltaLabel="vs January"
    />,
    <StatTile
      label="Net revenue retention"
      value={1.12}
      format="percent"
      context="Top quartile is 110%"
    />,
  ]}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/section.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/section.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Small multiple grid (`small-multiple-grid`)

> 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.

- Component: `SmallMultipleGrid` (import from `insightcharts`)
- Spec type: `"small-multiple-grid"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Faceting a chart form the `small-multiples` atom does not draw: stacked bars, scatter plots, donuts, waffles, dumbbells, histograms. Also when each panel should be a full chart with its own tooltip and axis.

### Avoid

Line, area or bar facets that must share one value scale: use the `small-multiples` atom, which draws every panel in one chart on a common axis. Here each panel scales to its own rows unless the spec fixes the axis (for example `option: { xAxis: { max: 70 } }`), so say so in the subtitle or fix it. More than about twelve panels.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/small-multiple-grid
```

The file lands at `components/insightcharts/molecules/small-multiple-grid.tsx`. `@insightcharts/small-multiple-grid-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, SmallMultipleGrid } from "insightcharts";

const data = [
  { country: "Netherlands", age: "16-24", Usually: 18, Sometimes: 22 },
  { country: "Netherlands", age: "25-34", Usually: 44, Sometimes: 21 },
  { country: "Netherlands", age: "35-49", Usually: 41, Sometimes: 19 },
  { country: "Netherlands", age: "50-64", Usually: 33, Sometimes: 17 },
  { country: "Netherlands", age: "65+", Usually: 14, Sometimes: 9 },
  { country: "Sweden", age: "16-24", Usually: 14, Sometimes: 20 },
  { country: "Sweden", age: "25-34", Usually: 39, Sometimes: 22 },
  { country: "Sweden", age: "35-49", Usually: 37, Sometimes: 20 },
  { country: "Sweden", age: "50-64", Usually: 30, Sometimes: 16 },
  { country: "Sweden", age: "65+", Usually: 11, Sometimes: 8 },
  { country: "Germany", age: "16-24", Usually: 9, Sometimes: 15 },
  { country: "Germany", age: "25-34", Usually: 24, Sometimes: 18 },
  { country: "Germany", age: "35-49", Usually: 23, Sometimes: 16 },
  { country: "Germany", age: "50-64", Usually: 18, Sometimes: 13 },
  { country: "Germany", age: "65+", Usually: 8, Sometimes: 6 },
  { country: "France", age: "16-24", Usually: 8, Sometimes: 12 },
  { country: "France", age: "25-34", Usually: 25, Sometimes: 14 },
  { country: "France", age: "35-49", Usually: 24, Sometimes: 13 },
  { country: "France", age: "50-64", Usually: 17, Sometimes: 10 },
  { country: "France", age: "65+", Usually: 7, Sometimes: 5 },
  { country: "Spain", age: "16-24", Usually: 5, Sometimes: 9 },
  { country: "Spain", age: "25-34", Usually: 13, Sometimes: 12 },
  { country: "Spain", age: "35-49", Usually: 13, Sometimes: 11 },
  { country: "Spain", age: "50-64", Usually: 10, Sometimes: 8 },
  { country: "Spain", age: "65+", Usually: 4, Sometimes: 4 },
  { country: "Italy", age: "16-24", Usually: 3, Sometimes: 6 },
  { country: "Italy", age: "25-34", Usually: 9, Sometimes: 8 },
  { country: "Italy", age: "35-49", Usually: 9, Sometimes: 8 },
  { country: "Italy", age: "50-64", Usually: 7, Sometimes: 6 },
  { country: "Italy", age: "65+", Usually: 3, Sometimes: 3 },
];

<SmallMultipleGrid
  title="65% of Dutch workers aged 25 to 34 worked from home usually or sometimes in 2023"
  subtitle="Share of employed people working from home usually or sometimes, by age group, six EU countries, 2023. All panels run from 0 to 70%"
  data={data}
  facet="country"
  columns={3}
  panelHeight={170}
  legend={["Usually", "Sometimes"]}
  chart={<BarChart
    x="age"
    y={["Usually", "Sometimes"]}
    stack
    sort="none"
    orientation="horizontal"
    format="{value}%"
    labels={false}
    legend={false}
    option={{ xAxis: { max: 70 } }}
  />}
  source="Eurostat, Labour Force Survey"
  note="Rounded, illustrative"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "small-multiple-grid",
  "title": "65% of Dutch workers aged 25 to 34 worked from home usually or sometimes in 2023",
  "subtitle": "Share of employed people working from home usually or sometimes, by age group, six EU countries, 2023. All panels run from 0 to 70%",
  "data": [
    { "country": "Netherlands", "age": "16-24", "Usually": 18, "Sometimes": 22 },
    { "country": "Netherlands", "age": "25-34", "Usually": 44, "Sometimes": 21 },
    { "country": "Netherlands", "age": "35-49", "Usually": 41, "Sometimes": 19 },
    { "country": "Netherlands", "age": "50-64", "Usually": 33, "Sometimes": 17 },
    { "country": "Netherlands", "age": "65+", "Usually": 14, "Sometimes": 9 },
    { "country": "Sweden", "age": "16-24", "Usually": 14, "Sometimes": 20 },
    { "country": "Sweden", "age": "25-34", "Usually": 39, "Sometimes": 22 },
    { "country": "Sweden", "age": "35-49", "Usually": 37, "Sometimes": 20 },
    { "country": "Sweden", "age": "50-64", "Usually": 30, "Sometimes": 16 },
    { "country": "Sweden", "age": "65+", "Usually": 11, "Sometimes": 8 },
    { "country": "Germany", "age": "16-24", "Usually": 9, "Sometimes": 15 },
    { "country": "Germany", "age": "25-34", "Usually": 24, "Sometimes": 18 },
    { "country": "Germany", "age": "35-49", "Usually": 23, "Sometimes": 16 },
    { "country": "Germany", "age": "50-64", "Usually": 18, "Sometimes": 13 },
    { "country": "Germany", "age": "65+", "Usually": 8, "Sometimes": 6 },
    { "country": "France", "age": "16-24", "Usually": 8, "Sometimes": 12 },
    { "country": "France", "age": "25-34", "Usually": 25, "Sometimes": 14 },
    { "country": "France", "age": "35-49", "Usually": 24, "Sometimes": 13 },
    { "country": "France", "age": "50-64", "Usually": 17, "Sometimes": 10 },
    { "country": "France", "age": "65+", "Usually": 7, "Sometimes": 5 },
    { "country": "Spain", "age": "16-24", "Usually": 5, "Sometimes": 9 },
    { "country": "Spain", "age": "25-34", "Usually": 13, "Sometimes": 12 },
    { "country": "Spain", "age": "35-49", "Usually": 13, "Sometimes": 11 },
    { "country": "Spain", "age": "50-64", "Usually": 10, "Sometimes": 8 },
    { "country": "Spain", "age": "65+", "Usually": 4, "Sometimes": 4 },
    { "country": "Italy", "age": "16-24", "Usually": 3, "Sometimes": 6 },
    { "country": "Italy", "age": "25-34", "Usually": 9, "Sometimes": 8 },
    { "country": "Italy", "age": "35-49", "Usually": 9, "Sometimes": 8 },
    { "country": "Italy", "age": "50-64", "Usually": 7, "Sometimes": 6 },
    { "country": "Italy", "age": "65+", "Usually": 3, "Sometimes": 3 }
  ],
  "facet": "country",
  "columns": 3,
  "panelHeight": 170,
  "legend": ["Usually", "Sometimes"],
  "chart": {
    "type": "bar-chart",
    "x": "age",
    "y": ["Usually", "Sometimes"],
    "stack": true,
    "sort": "none",
    "orientation": "horizontal",
    "format": "{value}%",
    "labels": false,
    "legend": false,
    "option": { "xAxis": { "max": 70 } }
  },
  "source": "Eurostat, Labour Force Survey",
  "note": "Rounded, illustrative"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `DataInput` |  | Rows for every panel together. Omit inside `<InsightData>`. |
| `transform` | `Transform \| Transform[]` |  | Applied before the rows are split by `facet`. |
| `facet` (required) | `string` |  | Field whose values each get a panel. |
| `chart` (required) | `InsightSpec \| (facet, rows) => ReactNode` |  | The chart repeated in every panel: a spec without `data` and without a `title`, or a render function from JSX. |
| `columns` | `number` |  | Preferred columns. Default: up to four, reduced to fit `minPanelWidth`. |
| `minPanelWidth` | `number` | `200` | Narrowest a panel may get before the grid drops a column. |
| `order` | `"data" \| "asc" \| "desc" \| string[]` | `"data"` | Panel order: data order, alphabetical, or an explicit list of facet values. |
| `panelHeight` | `number` | `160` | Plot height of each panel when the spec sets none. |
| `highlight` | `string \| string[]` |  | Passed to every panel as its `highlight`, so the same entity is emphasised everywhere. |
| `emphasis` | `string \| string[]` |  | Facet values whose panel titles are emphasised. |
| `legend` | `(string \| { label, color?, index?, shape?, muted? })[]` |  | One shared colour key above the panels (`legend-key` items, in series order). Set `legend: false` in the chart spec so panels do not repeat it. |
| `names` | `Record<string, string>` |  | Display names for facet values. |
| `level` | `2 \| 3 \| 4 \| 5 \| 6` | `4` | Heading level of the panel titles. |
| `title` | `string` |  | The main fact with its number, or a plain label. |
| `subtitle` | `string` |  | Measure, population, period, and whether the panels share a scale. |
| `source` | `string` |  | Shown under the grid as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to every panel. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [legend-key](https://insightcharts.dev/llms/legend-key.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [waffle-chart](https://insightcharts.dev/llms/waffle-chart.md)
- Used by: [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Shared highlight, two columns, emphasised panel

```tsx
import { BarChart, SmallMultipleGrid } from "insightcharts";

const data = [
  { country: "Netherlands", age: "16-24", Usually: 18, Sometimes: 22 },
  { country: "Netherlands", age: "25-34", Usually: 44, Sometimes: 21 },
  { country: "Netherlands", age: "35-49", Usually: 41, Sometimes: 19 },
  { country: "Netherlands", age: "50-64", Usually: 33, Sometimes: 17 },
  { country: "Netherlands", age: "65+", Usually: 14, Sometimes: 9 },
  { country: "Germany", age: "16-24", Usually: 9, Sometimes: 15 },
  { country: "Germany", age: "25-34", Usually: 24, Sometimes: 18 },
  { country: "Germany", age: "35-49", Usually: 23, Sometimes: 16 },
  // ... 12 more rows
];

<SmallMultipleGrid
  title="44% of Dutch workers aged 25 to 34 usually worked from home in 2023"
  subtitle="Share usually working from home, by age group, 2023. Panels are on their own scales"
  data={data}
  facet="country"
  columns={2}
  highlight="25-34"
  emphasis="Netherlands"
  chart={<BarChart x="age" y="Usually" sort="none" orientation="vertical" format="{value}%" />}
  note="Illustrative data"
/>
```

#### A waffle chart in each panel

```tsx
import { SmallMultipleGrid, WaffleChart } from "insightcharts";

const data = [
  { region: "Europe", group: "Online", share: 91 },
  { region: "Americas", group: "Online", share: 87 },
  { region: "Asia-Pacific", group: "Online", share: 66 },
  { region: "Africa", group: "Online", share: 37 },
];

<SmallMultipleGrid
  data={data}
  facet="region"
  panelHeight={150}
  chart={<WaffleChart name="group" value="share" total={100} legend={false} />}
  title="91% of people in Europe used the internet in 2023"
  subtitle="Share of the population using the internet, by region, 2023"
  source="ITU Facts and Figures 2023"
  note="Figures are approximate, for illustration"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/small-multiple-grid.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/small-multiple-grid.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Stat row (`stat-row`)

> Two to five key figures in one row separated by hairlines, collapsing to two columns and then one as the container narrows.

- Component: `StatRow` (import from `insightcharts`)
- Spec type: `"stat-row"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

The opening summary of a report or dashboard: the two to five most important numbers. Give every figure a delta or a context line, and order them by importance.

### Avoid

More than five figures (use `kpi-grid`), a single lead number (use `big-number` with `size: "hero"`), or figures that need their history shown (use `kpi-grid`, or `variant: "tiles"` with a `trend`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/stat-row
```

The file lands at `components/insightcharts/molecules/stat-row.tsx`. `@insightcharts/stat-row-demo` adds a ready-made example next to it.

### Usage

```tsx
import { StatRow } from "insightcharts";

<StatRow
  title="Renewables supplied 31.7% of the world's electricity in 2024"
  subtitle="Global electricity generation, 2024"
  items={[
    {
      value: 0.317,
      format: "percent",
      label: "Share from renewables",
      delta: "+1.9 pts",
      deltaLabel: "vs 2023",
    },
    { value: 2131, label: "Solar generation, TWh", delta: 0.29, deltaLabel: "vs 2023" },
    { value: 2494, label: "Wind generation, TWh", delta: 0.079, deltaLabel: "vs 2023" },
    {
      value: 0.409,
      format: "percent",
      label: "Share from all clean sources",
      context: "Above 40% for the first time since the 1940s",
    },
  ]}
  source="Ember, Global Electricity Review 2025"
  note="Figures are approximate, for illustration"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "stat-row",
  "title": "Renewables supplied 31.7% of the world's electricity in 2024",
  "subtitle": "Global electricity generation, 2024",
  "items": [
    {
      "value": 0.317,
      "format": "percent",
      "label": "Share from renewables",
      "delta": "+1.9 pts",
      "deltaLabel": "vs 2023"
    },
    { "value": 2131, "label": "Solar generation, TWh", "delta": 0.29, "deltaLabel": "vs 2023" },
    { "value": 2494, "label": "Wind generation, TWh", "delta": 0.079, "deltaLabel": "vs 2023" },
    {
      "value": 0.409,
      "format": "percent",
      "label": "Share from all clean sources",
      "context": "Above 40% for the first time since the 1940s"
    }
  ],
  "source": "Ember, Global Electricity Review 2025",
  "note": "Figures are approximate, for illustration"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` (required) | `{ value, label, context?, delta?, deltaLabel?, upIsGood?, format?, trend? }[]` |  | Two to five figures, most important first. Each takes the props of `big-number` (or `stat-tile` when `variant` is `tiles`). |
| `variant` | `"plain" \| "tiles"` | `"plain"` | Open figures divided by hairlines, or bordered tiles that can carry a `trend`. |
| `format` | `FormatSpec` | `"auto"` | Number format for every figure that does not set its own. |
| `title` | `string` |  | The main fact with its number, or a plain label. |
| `subtitle` | `string` |  | Population and period the figures share. |
| `source` | `string` |  | Shown under the row as "Source: ...". |
| `note` | `string` |  | Method note or caveat. |
| `theme` | `ThemeInput` |  | Theme override, passed on to every figure. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to every figure. |

### Composition

- Composes: [big-number](https://insightcharts.dev/llms/big-number.md), [stat-tile](https://insightcharts.dev/llms/stat-tile.md)
- Used by: [data-explorer](https://insightcharts.dev/llms/data-explorer.md), [executive-brief](https://insightcharts.dev/llms/executive-brief.md), [visual-essay](https://insightcharts.dev/llms/visual-essay.md)

### More examples

#### Tiles with trends

```tsx
import { StatRow } from "insightcharts";

<StatRow
  variant="tiles"
  items={[
    {
      label: "Monthly active users",
      value: 48210,
      format: "compact",
      delta: 0.083,
      deltaLabel: "vs September",
      trend: [38.1, 39.4, 39, 40.8, 42.2, 41.9, 43.5, 44.1, 44.5, 46, 47.2, 48.2],
    },
    {
      label: "Median first-response time",
      value: "2 h 14 min",
      delta: -0.18,
      deltaLabel: "vs September",
      upIsGood: false,
      trend: [4.1, 3.9, 3.8, 3.2, 3.4, 2.9, 2.7, 2.4, 2.2],
    },
    {
      label: "Net revenue retention",
      value: 1.12,
      format: "percent",
      context: "Top quartile for the sector is 110%",
    },
  ]}
  note="Illustrative data"
/>
```

#### Two figures

```tsx
import { StatRow } from "insightcharts";

<StatRow
  items={[
    {
      value: "1 in 4",
      label: "Households that could not cover a €500 bill",
      context: "Without borrowing or selling something",
    },
    {
      value: 0.068,
      format: "percent",
      label: "Households in arrears on utility bills",
      delta: "+0.4 pts",
      deltaLabel: "vs 2022",
      upIsGood: false,
    },
  ]}
  source="Eurostat, EU-SILC 2023"
  note="Figures are approximate, for illustration"
/>
```

#### Five figures

```tsx
import { StatRow } from "insightcharts";

<StatRow
  format="compact"
  items={[
    { value: 1284000, label: "Visits", delta: 0.12, deltaLabel: "vs last month" },
    { value: 412000, label: "Unique visitors", delta: 0.09, deltaLabel: "vs last month" },
    { value: 38200, label: "Sign-ups", delta: 0.031, deltaLabel: "vs last month" },
    { value: 5140, label: "Paid conversions", delta: -0.024, deltaLabel: "vs last month" },
    {
      value: 0.134,
      format: "percent",
      label: "Sign-up to paid",
      delta: "−0.7 pts",
      deltaLabel: "vs last month",
    },
  ]}
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/stat-row.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/stat-row.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Trend card (`trend-card`)

> A KPI card computed from a series: the latest value, its change against a baseline in the same data, and a sparkline of the series.

- Component: `TrendCard` (import from `insightcharts`)
- Spec type: `"trend-card"`
- Level: molecule. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

A metric whose recent history matters as much as its level: users, revenue, response time. Pass the series and field names; the figure, the change and the sparkline all come from the same rows, so they cannot disagree.

### Avoid

A number with no history (use `big-number` or `stat-tile`); several metrics from one dataset (use `kpi-grid`); a series the reader must read values from (use `line-chart`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/trend-card
```

The file lands at `components/insightcharts/molecules/trend-card.tsx`. `@insightcharts/trend-card-demo` adds a ready-made example next to it.

### Usage

```tsx
import { TrendCard } from "insightcharts";

const data = [
  { month: "2024-01-01", users: 38100 },
  { month: "2024-02-01", users: 39400 },
  { month: "2024-03-01", users: 39000 },
  { month: "2024-04-01", users: 40800 },
  { month: "2024-05-01", users: 42200 },
  { month: "2024-06-01", users: 41900 },
  { month: "2024-07-01", users: 43500 },
  { month: "2024-08-01", users: 44100 },
  { month: "2024-09-01", users: 44500 },
  { month: "2024-10-01", users: 46000 },
  { month: "2024-11-01", users: 47200 },
  { month: "2024-12-01", users: 48210 },
];

<TrendCard
  label="Monthly active users"
  data={data}
  x="month"
  y="users"
  format="compact"
  style={{ maxWidth: 300 }}
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "trend-card",
  "label": "Monthly active users",
  "data": [
    { "month": "2024-01-01", "users": 38100 },
    { "month": "2024-02-01", "users": 39400 },
    { "month": "2024-03-01", "users": 39000 },
    { "month": "2024-04-01", "users": 40800 },
    { "month": "2024-05-01", "users": 42200 },
    { "month": "2024-06-01", "users": 41900 },
    { "month": "2024-07-01", "users": 43500 },
    { "month": "2024-08-01", "users": 44100 },
    { "month": "2024-09-01", "users": 44500 },
    { "month": "2024-10-01", "users": 46000 },
    { "month": "2024-11-01", "users": 47200 },
    { "month": "2024-12-01", "users": 48210 }
  ],
  "x": "month",
  "y": "users",
  "format": "compact",
  "style": { "maxWidth": 300 }
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` (required) | `string` |  | What the figure measures, sentence case. |
| `data` | `DataInput` |  | Rows in time order, one per period. Omit inside `<InsightData>`. |
| `transform` | `Transform \| Transform[]` |  | Applied to the rows before anything is computed. |
| `y` (required) | `string` |  | Value field: the series drawn and the source of the figure and its change. |
| `x` | `string` |  | Period field, used to name the baseline and in the sparkline tooltip. |
| `value` | `number \| string` |  | The figure shown. Default: the last row's `y`. |
| `delta` | `number \| string` |  | The change shown. Default: computed from the series according to `compare`. |
| `compare` | `"first" \| "previous" \| number` | `"first"` | Baseline for the computed change: first row, previous row, or a number of rows back (12 for year-on-year in monthly data). |
| `change` | `"percent" \| "absolute"` | `"percent"` | Relative change, or the difference between the two values (use for rates and shares). An absolute change of a percentage is shown in percentage points. |
| `deltaFormat` | `FormatSpec` |  | Format for a computed absolute change, e.g. `"{value} pp"` or `"signed"`. Default: points ("+1.9 pts") when `format` is a percentage, otherwise `format`. |
| `deltaLabel` | `string` |  | What the change is against. Default: "since {first period}" when `x` is given. |
| `upIsGood` | `boolean` | `true` | Whether an increase is good news; decides the delta colour. |
| `context` | `string` |  | A line under the figure that gives it meaning. |
| `format` | `FormatSpec` | `"auto"` | Number format for the figure and the sparkline tooltip. |
| `kind` | `"line" \| "bar"` | `"line"` | Sparkline form: a line for a trend, bars for discrete counts. |
| `area` | `boolean` | `false` | Light fill under the line; the scale then includes zero. |
| `trendPosition` | `"bottom" \| "right"` | `"bottom"` | Where the sparkline sits; `right` falls back to `bottom` in narrow cards. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the tile and sparkline. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [stat-tile](https://insightcharts.dev/llms/stat-tile.md), [sparkline](https://insightcharts.dev/llms/sparkline.md)
- Used by: [kpi-grid](https://insightcharts.dev/llms/kpi-grid.md)

### More examples

#### Down is good, trend on the right

```tsx
import { TrendCard } from "insightcharts";

const data = [
  { month: "2024-01-01", hours: 4.1 },
  { month: "2024-02-01", hours: 3.9 },
  { month: "2024-03-01", hours: 3.8 },
  { month: "2024-04-01", hours: 3.2 },
  { month: "2024-05-01", hours: 3.4 },
  { month: "2024-06-01", hours: 2.9 },
  { month: "2024-07-01", hours: 2.7 },
  { month: "2024-08-01", hours: 2.4 },
  // ... 1 more rows
];

<TrendCard
  label="Median first-response time"
  data={data}
  x="month"
  y="hours"
  format="{value} h"
  upIsGood={false}
  trendPosition="right"
  style={{ maxWidth: 440 }}
/>
```

#### Absolute change against the previous period, bars

```tsx
import { TrendCard } from "insightcharts";

const data = [
  { month: "2024-01-01", rate: 3.9 },
  { month: "2024-02-01", rate: 3.8 },
  { month: "2024-03-01", rate: 3.8 },
  { month: "2024-04-01", rate: 3.6 },
  { month: "2024-05-01", rate: 3.5 },
  { month: "2024-06-01", rate: 3.6 },
  { month: "2024-07-01", rate: 3.4 },
  { month: "2024-08-01", rate: 3.7 },
  // ... 4 more rows
];

<TrendCard
  label="Unemployment rate"
  data={data}
  x="month"
  y="rate"
  format="{value}%"
  compare="previous"
  change="absolute"
  upIsGood={false}
  kind="bar"
  context="Highest month of 2024"
  style={{ maxWidth: 300 }}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/trend-card.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/molecules/trend-card.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Atlas poster (`atlas-poster`)

> 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.

- Component: `AtlasPoster` (import from `insightcharts`)
- Spec type: `"atlas-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when one subject has many small facts of different kinds (shares, places, a trend, a change, a ranking, a map) and none of them should dominate: a crop, an industry, a service, a country's internet. Fill at least eight regions. Give every panel a short heading that states its one number. Every region is optional, and each band shares its width among the panels that are present.

### Avoid

One dominant fact or graphic (use `count-poster`, `flow-poster` or `ranking-poster`). The same measures across several entities (use `matrix-poster`). Fewer than six panels (use `poster` and place them yourself). A phone-first piece: the spread becomes one long column under 600px.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/atlas-poster
```

The file lands at `components/insightcharts/templates/atlas-poster.tsx`. `@insightcharts/atlas-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { AtlasPoster } from "insightcharts";

<AtlasPoster
  theme="forest"
  kicker="Food"
  title="Norland's orchards picked 2.4 million tonnes of apples in 2025"
  subtitle="Harvest, regions, varieties, prices and exports of the apple crop."
  statement={{
    value: "2.4m",
    label: "Tonnes of apples picked in 2025",
    context: "2.1 million tonnes in 2024",
    icon: "apple",
  }}
  spokes={{
    data: [
      { use: "Eaten fresh", share: 38 },
      { use: "Juice", share: 24 },
      { use: "Cider", share: 15 },
      { use: "Sauce and purée", share: 9 },
      { use: "Dried", share: 5 },
      { use: "Animal feed", share: 5 },
      { use: "Vinegar", share: 4 },
    ],
    name: "use",
    value: "share",
    format: "{value}%",
    icon: "apple",
    highlight: "Eaten fresh",
    title: "38% of the harvest was eaten fresh",
  }}
  network={{
    data: [
      { region: "Eastmark", kt: 720 },
      { region: "Sundby", kt: 540 },
      { region: "Lowlands", kt: 460 },
      { region: "Highmoor", kt: 310 },
      { region: "Fjordland", kt: 220 },
      { region: "Aldern", kt: 150 },
    ],
    name: "region",
    value: "kt",
    links: [
      { from: "Eastmark", to: "Sundby" },
      { from: "Eastmark", to: "Lowlands" },
      { from: "Eastmark", to: "Highmoor" },
      { from: "Eastmark", to: "Aldern" },
      { from: "Sundby", to: "Fjordland" },
      { from: "Lowlands", to: "Fjordland" },
    ],
    highlight: "Eastmark",
    tag: "Largest",
    format: "{value} kt",
    title: "Eastmark picked 720,000 tonnes",
    subtitle: "Harvest by region, thousand tonnes. Lines are fruit-train routes.",
  }}
  trend={{
    data: [
      { year: "2010", mt: 1.5 },
      { year: "2011", mt: 1.56 },
      { year: "2012", mt: 1.48 },
      { year: "2013", mt: 1.65 },
      { year: "2014", mt: 1.72 },
      { year: "2015", mt: 1.69 },
      { year: "2016", mt: 1.81 },
      { year: "2017", mt: 1.9 },
      { year: "2018", mt: 2.05 },
      { year: "2019", mt: 2.2 },
      { year: "2020", mt: 2.52 },
      { year: "2021", mt: 2.31 },
      { year: "2022", mt: 1.98 },
      { year: "2023", mt: 2.15 },
      { year: "2024", mt: 2.1 },
      { year: "2025", mt: 2.4 },
    ],
    x: "year",
    y: "mt",
    format: "{value}m t",
    title: "The harvest was 2.52 million tonnes in 2020",
    subtitle: "Apples picked per year, million tonnes, 2010 to 2025",
  }}
  area={{
    data: [{ land: "All farmland", ha: 2100000 }, { land: "Orchards", ha: 84000 }],
    name: "land",
    value: "ha",
    format: "compact",
    ratio: "{ratio}x the area",
    title: "Orchards covered 84,000 hectares",
    subtitle: "Hectares, 2025",
  }}
  slope={{
    data: [
      { variety: "Gala", y2015: 22, y2025: 27 },
      { variety: "Elstar", y2015: 25, y2025: 18 },
      { variety: "Jonagold", y2015: 20, y2025: 14 },
      { variety: "Braeburn", y2015: 12, y2025: 15 },
    ],
    series: "variety",
    y: ["y2015", "y2025"],
    names: { y2015: "2015", y2025: "2025" },
    highlight: "Gala",
    format: "{value}%",
    title: "Gala rose from 22% to 27% of the harvest",
  }}
  rank={{
    data: [
      { country: "Vesterhav", kt: 190 },
      { country: "Kalmar", kt: 140 },
      { country: "Ostland", kt: 95 },
      { country: "Meridia", kt: 60 },
      { country: "Tavria", kt: 35 },
    ],
    name: "country",
    value: "kt",
    format: "{value} kt",
    highlight: "Vesterhav",
    title: "Vesterhav bought 190,000 tonnes",
  }}
  parts={{
    data: [
      { part: "Shop", cents: 71 },
      { part: "Grower", cents: 62 },
      { part: "Packing and storage", cents: 34 },
      { part: "Transport", cents: 21 },
      { part: "Sales tax", cents: 17 },
    ],
    name: "part",
    value: "cents",
    format: "{value}c",
    highlight: "Grower",
    title: "Growers received 62 cents of a €2.05 kilo",
  }}
  map={{
    data: [
      { region: "Fjordland", code: "Fj", yield: 22, col: 0, row: 0 },
      { region: "Highmoor", code: "Hi", yield: 27, col: 1, row: 0 },
      { region: "Norvik", code: "No", yield: 19, col: 2, row: 0 },
      { region: "Aldern", code: "Al", yield: 24, col: 0, row: 1 },
      { region: "Eastmark", code: "Ea", yield: 41, col: 1, row: 1 },
      { region: "Castren", code: "Ca", yield: 33, col: 2, row: 1 },
      { region: "Lowlands", code: "Lo", yield: 35, col: 1, row: 2 },
      { region: "Sundby", code: "Su", yield: 38, col: 2, row: 2 },
    ],
    region: "region",
    value: "yield",
    code: "code",
    title: "Eastmark picked 41 tonnes a hectare",
    subtitle: "Yield by region, tonnes per hectare",
  }}
  circles={{
    data: [
      { who: "per person in Norland", kg: 24 },
      { who: "per person in Vesterhav", kg: 17 },
      { who: "per person in Kalmar", kg: 9 },
    ],
    name: "who",
    value: "kg",
    unit: "kg",
    title: "Norlanders ate 24 kg of apples each",
  }}
  stats={[
    { icon: "apple", count: 4, total: 10, text: "apples were sold loose." },
    { icon: "book", count: 2, total: 10, text: "pickers were students." },
    { icon: "tree", count: 3, total: 10, text: "orchard trees were under ten years old." },
  ]}
  sources={["Norland Fruit Growers' Association", "Norland Statistics Office"]}
  note="Norland and its neighbours are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "atlas-poster",
  "theme": "forest",
  "kicker": "Food",
  "title": "Norland's orchards picked 2.4 million tonnes of apples in 2025",
  "subtitle": "Harvest, regions, varieties, prices and exports of the apple crop.",
  "statement": {
    "value": "2.4m",
    "label": "Tonnes of apples picked in 2025",
    "context": "2.1 million tonnes in 2024",
    "icon": "apple"
  },
  "spokes": {
    "data": [
      { "use": "Eaten fresh", "share": 38 },
      { "use": "Juice", "share": 24 },
      { "use": "Cider", "share": 15 },
      { "use": "Sauce and purée", "share": 9 },
      { "use": "Dried", "share": 5 },
      { "use": "Animal feed", "share": 5 },
      { "use": "Vinegar", "share": 4 }
    ],
    "name": "use",
    "value": "share",
    "format": "{value}%",
    "icon": "apple",
    "highlight": "Eaten fresh",
    "title": "38% of the harvest was eaten fresh"
  },
  "network": {
    "data": [
      { "region": "Eastmark", "kt": 720 },
      { "region": "Sundby", "kt": 540 },
      { "region": "Lowlands", "kt": 460 },
      { "region": "Highmoor", "kt": 310 },
      { "region": "Fjordland", "kt": 220 },
      { "region": "Aldern", "kt": 150 }
    ],
    "name": "region",
    "value": "kt",
    "links": [
      { "from": "Eastmark", "to": "Sundby" },
      { "from": "Eastmark", "to": "Lowlands" },
      { "from": "Eastmark", "to": "Highmoor" },
      { "from": "Eastmark", "to": "Aldern" },
      { "from": "Sundby", "to": "Fjordland" },
      { "from": "Lowlands", "to": "Fjordland" }
    ],
    "highlight": "Eastmark",
    "tag": "Largest",
    "format": "{value} kt",
    "title": "Eastmark picked 720,000 tonnes",
    "subtitle": "Harvest by region, thousand tonnes. Lines are fruit-train routes."
  },
  "trend": {
    "data": [
      { "year": "2010", "mt": 1.5 },
      { "year": "2011", "mt": 1.56 },
      { "year": "2012", "mt": 1.48 },
      { "year": "2013", "mt": 1.65 },
      { "year": "2014", "mt": 1.72 },
      { "year": "2015", "mt": 1.69 },
      { "year": "2016", "mt": 1.81 },
      { "year": "2017", "mt": 1.9 },
      { "year": "2018", "mt": 2.05 },
      { "year": "2019", "mt": 2.2 },
      { "year": "2020", "mt": 2.52 },
      { "year": "2021", "mt": 2.31 },
      { "year": "2022", "mt": 1.98 },
      { "year": "2023", "mt": 2.15 },
      { "year": "2024", "mt": 2.1 },
      { "year": "2025", "mt": 2.4 }
    ],
    "x": "year",
    "y": "mt",
    "format": "{value}m t",
    "title": "The harvest was 2.52 million tonnes in 2020",
    "subtitle": "Apples picked per year, million tonnes, 2010 to 2025"
  },
  "area": {
    "data": [{ "land": "All farmland", "ha": 2100000 }, { "land": "Orchards", "ha": 84000 }],
    "name": "land",
    "value": "ha",
    "format": "compact",
    "ratio": "{ratio}x the area",
    "title": "Orchards covered 84,000 hectares",
    "subtitle": "Hectares, 2025"
  },
  "slope": {
    "data": [
      { "variety": "Gala", "y2015": 22, "y2025": 27 },
      { "variety": "Elstar", "y2015": 25, "y2025": 18 },
      { "variety": "Jonagold", "y2015": 20, "y2025": 14 },
      { "variety": "Braeburn", "y2015": 12, "y2025": 15 }
    ],
    "series": "variety",
    "y": ["y2015", "y2025"],
    "names": { "y2015": "2015", "y2025": "2025" },
    "highlight": "Gala",
    "format": "{value}%",
    "title": "Gala rose from 22% to 27% of the harvest"
  },
  "rank": {
    "data": [
      { "country": "Vesterhav", "kt": 190 },
      { "country": "Kalmar", "kt": 140 },
      { "country": "Ostland", "kt": 95 },
      { "country": "Meridia", "kt": 60 },
      { "country": "Tavria", "kt": 35 }
    ],
    "name": "country",
    "value": "kt",
    "format": "{value} kt",
    "highlight": "Vesterhav",
    "title": "Vesterhav bought 190,000 tonnes"
  },
  "parts": {
    "data": [
      { "part": "Shop", "cents": 71 },
      { "part": "Grower", "cents": 62 },
      { "part": "Packing and storage", "cents": 34 },
      { "part": "Transport", "cents": 21 },
      { "part": "Sales tax", "cents": 17 }
    ],
    "name": "part",
    "value": "cents",
    "format": "{value}c",
    "highlight": "Grower",
    "title": "Growers received 62 cents of a €2.05 kilo"
  },
  "map": {
    "data": [
      { "region": "Fjordland", "code": "Fj", "yield": 22, "col": 0, "row": 0 },
      { "region": "Highmoor", "code": "Hi", "yield": 27, "col": 1, "row": 0 },
      { "region": "Norvik", "code": "No", "yield": 19, "col": 2, "row": 0 },
      { "region": "Aldern", "code": "Al", "yield": 24, "col": 0, "row": 1 },
      { "region": "Eastmark", "code": "Ea", "yield": 41, "col": 1, "row": 1 },
      { "region": "Castren", "code": "Ca", "yield": 33, "col": 2, "row": 1 },
      { "region": "Lowlands", "code": "Lo", "yield": 35, "col": 1, "row": 2 },
      { "region": "Sundby", "code": "Su", "yield": 38, "col": 2, "row": 2 }
    ],
    "region": "region",
    "value": "yield",
    "code": "code",
    "title": "Eastmark picked 41 tonnes a hectare",
    "subtitle": "Yield by region, tonnes per hectare"
  },
  "circles": {
    "data": [
      { "who": "per person in Norland", "kg": 24 },
      { "who": "per person in Vesterhav", "kg": 17 },
      { "who": "per person in Kalmar", "kg": 9 }
    ],
    "name": "who",
    "value": "kg",
    "unit": "kg",
    "title": "Norlanders ate 24 kg of apples each"
  },
  "stats": [
    { "icon": "apple", "count": 4, "total": 10, "text": "apples were sold loose." },
    { "icon": "book", "count": 2, "total": 10, "text": "pickers were students." },
    { "icon": "tree", "count": 3, "total": 10, "text": "orchard trees were under ten years old." }
  ],
  "sources": ["Norland Fruit Growers' Association", "Norland Statistics Office"],
  "note": "Norland and its neighbours are invented. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `statement` | `{ value, label, context?, icon? }` |  | Band 1, left: the subject's main number in large light type, in the accent colour. |
| `spokes` | `{ data, name, value, icon?, centerLabel?, highlight?, title?, ...radial-spokes props } \| Slot` |  | Band 1, middle: 4 to 12 attributes as spokes round a centre icon (`radial-spokes`). |
| `network` | `{ data, name, value, links, highlight?, tag?, title?, ...bubble-network props } \| Slot` |  | Band 1, right: named places or things as circles sized by value and joined by lines (`bubble-network`). |
| `trend` | `{ data, x, y, peak?, format?, title?, ...area-chart props } \| Slot` |  | Band 2, wide: one measure over an ordered dimension as a smooth filled curve (`area-chart`). The highest point is labelled with its value and position; `peak` replaces that label, and `peak: false` removes it. |
| `area` | `{ data, name, value, ratio?, title?, ...proportional-area props } \| Slot` |  | Band 2: two or three quantities as squares nested from one corner, with a bracket stating the ratio (`proportional-area`, `layout: "nested"`). |
| `slope` | `{ data, series, y: [from, to], names?, highlight?, title?, ...slope-chart props } \| Slot` |  | Band 2: each entity at two dates, joined by a line and labelled at the end (`slope-chart`). |
| `rank` | `{ data, name, value, highlight?, title?, ...pill-rank props } \| Slot` |  | Band 3: a ranking of 4 to 6 rows as centred pills (`pill-rank`). Pass a `bar-chart` spec for bars instead. |
| `parts` | `{ data, name, value, title?, ...treemap props } \| Slot` |  | Band 3: the parts of one whole as tiles (`treemap`). |
| `map` | `{ data, region, value, code?, geo?, title?, ...choropleth-map props } \| Slot` |  | Band 3: a tile map shaded by value (`choropleth-map`). Give every row `col` and `row`, the tile's place in the grid, and the template builds the squares; `code` names the field printed on each tile. Pass `geo` to use your own GeoJSON. |
| `circles` | `{ data, name, value, unit?, title?, ...stat-circles props } \| Slot` |  | Band 3: two to four magnitudes as sized circles (`stat-circles`). |
| `stats` | `{ count, total?, text, icon?, value? }[]` |  | Closing row: up to three "3 in 10" statements, each a row of icons with some filled (`icon-stat`). |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"forest"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `1440` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [radial-spokes](https://insightcharts.dev/llms/radial-spokes.md), [bubble-network](https://insightcharts.dev/llms/bubble-network.md), [area-chart](https://insightcharts.dev/llms/area-chart.md), [proportional-area](https://insightcharts.dev/llms/proportional-area.md), [slope-chart](https://insightcharts.dev/llms/slope-chart.md), [pill-rank](https://insightcharts.dev/llms/pill-rank.md), [treemap](https://insightcharts.dev/llms/treemap.md), [choropleth-map](https://insightcharts.dev/llms/choropleth-map.md), [stat-circles](https://insightcharts.dev/llms/stat-circles.md), [icon-stat](https://insightcharts.dev/llms/icon-stat.md)
- Used by: no molecule or template yet

### More examples

#### Dusk, a space programme, ten panels, with download

```tsx
import { AtlasPoster } from "insightcharts";

<AtlasPoster
  theme="dusk"
  download
  kicker="Space"
  title="The Norland Space Agency put 42 satellites into orbit in 2025"
  subtitle="Satellites, launches, ground stations, costs and budget of one national space programme."
  statement={{ value: "42", label: "Satellites launched in 2025", context: "38 in 2024", icon: "satellite" }}
  spokes={{
    data: [
      { purpose: "Earth observation", n: 14 },
      { purpose: "Communications", n: 11 },
      { purpose: "Navigation", n: 6 },
      { purpose: "Weather", n: 5 },
      { purpose: "Science", n: 4 },
      { purpose: "Technology tests", n: 2 },
    ],
    name: "purpose",
    value: "n",
    icon: "satellite",
    highlight: "Earth observation",
    title: "14 of the satellites observe the Earth",
  }}
  network={{
    data: [
      { station: "Skarvik", passes: 96 },
      { station: "Holm Pass", passes: 64 },
      { station: "Sundby", passes: 48 },
      { station: "Tarn Head", passes: 31 },
      { station: "Aldern", passes: 22 },
    ],
    name: "station",
    value: "passes",
    links: [
      { from: "Skarvik", to: "Holm Pass" },
      { from: "Skarvik", to: "Sundby" },
      { from: "Skarvik", to: "Tarn Head" },
      { from: "Skarvik", to: "Aldern" },
      { from: "Sundby", to: "Aldern" },
    ],
    highlight: "Skarvik",
    tag: "Control centre",
    title: "Skarvik tracked 96 satellite passes a day",
    subtitle: "Passes tracked per day by ground station. Lines are data links.",
  }}
  trend={{
    data: [
      { year: "2013", n: 3 },
      { year: "2014", n: 4 },
      { year: "2015", n: 4 },
      { year: "2016", n: 6 },
      { year: "2017", n: 9 },
      { year: "2018", n: 8 },
      { year: "2019", n: 13 },
      { year: "2020", n: 17 },
      { year: "2021", n: 24 },
      { year: "2022", n: 31 },
      { year: "2023", n: 46 },
      { year: "2024", n: 38 },
      { year: "2025", n: 42 },
    ],
    x: "year",
    y: "n",
    format: "integer",
    title: "The agency launched 46 satellites in 2023",
    subtitle: "Satellites put into orbit per year, 2013 to 2025",
  }}
  area={{
    data: [{ year: "2025", t: 60 }, { year: "2015", t: 4 }],
    name: "year",
    value: "t",
    format: "{value} t",
    ratio: "{ratio}x the mass",
    title: "60 tonnes reached orbit in 2025",
    subtitle: "Mass put into orbit per year, tonnes",
  }}
  slope={{
    data: [
      { rocket: "Small launcher", y2015: 41, y2025: 18 },
      { rocket: "Medium launcher", y2015: 22, y2025: 7 },
      { rocket: "Shared ride", y2015: 15, y2025: 4 },
    ],
    series: "rocket",
    y: ["y2015", "y2025"],
    names: { y2015: "2015", y2025: "2025" },
    highlight: "Shared ride",
    format: "€{value}k",
    title: "A shared ride cost €4,000 a kilogram in 2025",
    subtitle: "Launch price per kilogram, thousand euros",
  }}
  rank={{
    data: [
      { programme: "Launch services", m: 310 },
      { programme: "Earth observation", m: 240 },
      { programme: "Communications", m: 150 },
      { programme: "Science missions", m: 90 },
      { programme: "Ground stations", m: 60 },
    ],
    name: "programme",
    value: "m",
    format: "€{value}m",
    highlight: "Launch services",
    title: "Launch services cost €310 million",
  }}
  parts={{
    data: [
      { builder: "Agency workshops", n: 18 },
      { builder: "Universities", n: 13 },
      { builder: "Industry", n: 11 },
    ],
    name: "builder",
    value: "n",
    highlight: "Universities",
    title: "Universities built 13 of the 42 satellites",
  }}
  circles={{
    data: [
      { kind: "kg, relay satellite", kg: 4200 },
      { kind: "kg, weather satellite", kg: 1100 },
      { kind: "kg, cubesat", kg: 12 },
    ],
    name: "kind",
    value: "kg",
    format: "integer",
    title: "A relay satellite weighs 4,200 kg",
  }}
  stats={[
    { icon: "rocket", count: 9, total: 10, text: "launches reached their planned orbit." },
    { icon: "satellite", count: 3, total: 10, text: "satellites were built by universities." },
  ]}
  sources="Norland Space Agency annual report 2025"
  note="The Norland Space Agency is invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Sunrise, a country's internet, linked

```tsx
import { AtlasPoster } from "insightcharts";

<AtlasPoster
  theme="sunrise"
  linked
  kicker="The internet"
  title="94% of Norland's households were online in 2025"
  subtitle="Use, traffic, networks and speeds of the internet in one country."
  statement={{
    value: "94%",
    label: "Households with an internet connection in 2025",
    context: "81% in 2015",
    icon: "laptop",
  }}
  spokes={{
    data: [
      { use: "Messaging", share: 81 },
      { use: "Video", share: 64 },
      { use: "News", share: 52 },
      { use: "Shopping", share: 31 },
      { use: "Banking", share: 28 },
      { use: "Learning", share: 12 },
      { use: "Games", share: 24 },
    ],
    name: "use",
    value: "share",
    format: "{value}%",
    icon: "phone",
    highlight: "Messaging",
    title: "81% of adults sent a message online every day",
  }}
  network={{
    data: [
      { site: "Norvik", mw: 180 },
      { site: "Castren", mw: 120 },
      { site: "Sundby", mw: 75 },
      { site: "Eastmark", mw: 40 },
      { site: "Aldern", mw: 25 },
      { site: "Skarvik", mw: 15 },
    ],
    name: "site",
    value: "mw",
    links: [
      { from: "Norvik", to: "Castren" },
      { from: "Norvik", to: "Sundby" },
      { from: "Norvik", to: "Skarvik" },
      { from: "Norvik", to: "Aldern" },
      { from: "Castren", to: "Eastmark" },
      { from: "Sundby", to: "Eastmark" },
    ],
    highlight: "Norvik",
    tag: "Main exchange",
    format: "{value} MW",
    title: "Norvik's data centres drew 180 MW",
    subtitle: "Data-centre power by site, megawatts. Lines are trunk fibre routes.",
  }}
  trend={{
    data: [
      { hour: "00:00", gbps: 31 },
      { hour: "01:00", gbps: 22 },
      { hour: "02:00", gbps: 16 },
      { hour: "03:00", gbps: 13 },
      { hour: "04:00", gbps: 12 },
      { hour: "05:00", gbps: 15 },
      { hour: "06:00", gbps: 24 },
      { hour: "07:00", gbps: 38 },
      { hour: "08:00", gbps: 47 },
      { hour: "09:00", gbps: 52 },
      { hour: "10:00", gbps: 55 },
      { hour: "11:00", gbps: 58 },
      { hour: "12:00", gbps: 61 },
      { hour: "13:00", gbps: 60 },
      { hour: "14:00", gbps: 59 },
      { hour: "15:00", gbps: 62 },
      { hour: "16:00", gbps: 68 },
      { hour: "17:00", gbps: 77 },
      { hour: "18:00", gbps: 88 },
      { hour: "19:00", gbps: 97 },
      { hour: "20:00", gbps: 104 },
      { hour: "21:00", gbps: 98 },
      { hour: "22:00", gbps: 76 },
      { hour: "23:00", gbps: 49 },
    ],
    x: "hour",
    y: "gbps",
    format: "{value} Gbps",
    title: "Traffic reached 104 Gbps at 8pm",
    subtitle: "Traffic at the Norvik exchange by hour, an average weekday in 2025",
  }}
  area={{
    data: [{ homes: "All homes", k: 2600 }, { homes: "Homes with fibre", k: 1590 }],
    name: "homes",
    value: "k",
    format: "{value}k",
    ratio: false,
    title: "1.59 million of 2.6 million homes had fibre",
  }}
  slope={{
    data: [
      { tech: "Fibre", y2015: 8, y2025: 61 },
      { tech: "Cable", y2015: 34, y2025: 22 },
      { tech: "Copper line", y2015: 51, y2025: 9 },
      { tech: "Mobile only", y2015: 7, y2025: 8 },
    ],
    series: "tech",
    y: ["y2015", "y2025"],
    names: { y2015: "2015", y2025: "2025" },
    highlight: "Fibre",
    format: "{value}%",
    title: "Fibre rose from 8% to 61% of connections",
  }}
  rank={{
    data: [
      { region: "Norvik", mbps: 412 },
      { region: "Castren", mbps: 368 },
      { region: "Sundby", mbps: 290 },
      { region: "Eastmark", mbps: 214 },
      { region: "Highmoor", mbps: 96 },
    ],
    name: "region",
    value: "mbps",
    format: "{value} Mbps",
    highlight: "Norvik",
    title: "Norvik's median download speed was 412 Mbps",
  }}
  parts={{
    data: [
      { kind: "Video", share: 58 },
      { kind: "Games and downloads", share: 14 },
      { kind: "Web and apps", share: 12 },
      { kind: "Video calls", share: 9 },
      { kind: "Other", share: 7 },
    ],
    name: "kind",
    value: "share",
    format: "{value}%",
    highlight: "Video",
    title: "Video was 58% of traffic",
  }}
  map={{
    data: [
      { region: "Fjordland", code: "Fj", share: 34, col: 0, row: 0 },
      { region: "Highmoor", code: "Hi", share: 28, col: 1, row: 0 },
      { region: "Norvik", code: "No", share: 86, col: 2, row: 0 },
      { region: "Aldern", code: "Al", share: 47, col: 0, row: 1 },
      { region: "Eastmark", code: "Ea", share: 58, col: 1, row: 1 },
      { region: "Castren", code: "Ca", share: 79, col: 2, row: 1 },
      { region: "Lowlands", code: "Lo", share: 52, col: 1, row: 2 },
      { region: "Sundby", code: "Su", share: 71, col: 2, row: 2 },
    ],
    region: "region",
    value: "share",
    code: "code",
    format: "{value}%",
    title: "Fibre reached 86% of homes in Norvik",
    subtitle: "Homes with fibre available, by region",
  }}
  circles={{
    data: [
      { year: "GB a month in 2015", gb: 38 },
      { year: "GB a month in 2020", gb: 142 },
      { year: "GB a month in 2025", gb: 410 },
    ],
    name: "year",
    value: "gb",
    format: "integer",
    title: "A household used 410 GB a month in 2025",
  }}
  stats={[
    { icon: "cart", count: 1, total: 10, text: "adults had never bought anything online." },
    { icon: "phone", count: 7, total: 10, text: "minutes online were spent on a phone." },
    { icon: "lock", count: 4, total: 10, text: "adults used a password manager." },
  ]}
  sources={["Norland Communications Authority", "Norvik Internet Exchange"]}
  note="Norland is an invented country. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/atlas-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/atlas-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Comparison brief (`comparison-brief`)

> A compared with B on one page. It has a headline that states the result, the headline figures mirrored either side of their labels, one hero exhibit that shows both sides, paired exhibits on a shared scale, a verdict callout and a source note.

- Component: `ComparisonBrief` (import from `insightcharts`)
- Spec type: `"comparison-brief"`
- Level: template. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for two things a reader has to choose between or compare, such as two countries, two products or a before and an after. Write the result with its number in the headline. Put the four or five most important measures in `figures`. Use a two-series line, dumbbell, slope or `before-after` as the hero. In each pair, use the same chart form and the same scale for both sides. The `subject` side takes the accent colour everywhere and the other side stays grey.

### Avoid

Three or more things (use a `comparison-table` or `small-multiple-grid` inside a `report-page`). One thing over time with nothing to compare it with (use `timeline-story`). Paired charts on different scales, because readers compare bar lengths across the pair.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/comparison-brief
```

The file lands at `components/insightcharts/templates/comparison-brief.tsx`. `@insightcharts/comparison-brief-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, ComparisonBrief, LineChart, SegmentedBar } from "insightcharts";

<ComparisonBrief
  kicker="Home heating"
  title="With the £7,500 grant, a heat pump repays its extra £500 cost in 4 years"
  deck="After the grant a heat pump costs £3,500 to buy and fit. A gas boiler costs £3,000. The heat pump costs £855 a year to run. The boiler costs £980."
  a={{ name: "Heat pump", detail: "Air source, 7 kW" }}
  b={{ name: "Gas boiler", detail: "Condensing combi, 30 kW" }}
  figures={[
    {
      label: "Cost to buy and fit, after grant",
      a: 3500,
      b: 3000,
      format: { style: "currency", currency: "GBP", maximumFractionDigits: 0 },
      better: "lower",
    },
    { label: "Running cost per year", a: 855, b: 980, format: "currency:GBP", better: "lower" },
    { label: "CO2 per year, tonnes", a: 0.6, b: 2.3, format: "decimal:1", better: "lower" },
    {
      label: "Heat out per unit of energy in",
      a: 3.2,
      b: 0.9,
      format: "decimal:1",
      better: "higher",
    },
    { label: "Expected life, years", a: 20, b: 15, better: "higher" },
  ]}
  hero={<LineChart
    data={[
      { year: "0", saving: -500 },
      { year: "1", saving: -375 },
      { year: "2", saving: -250 },
      { year: "3", saving: -125 },
      { year: "4", saving: 0 },
      { year: "5", saving: 125 },
      { year: "6", saving: 250 },
      { year: "7", saving: 375 },
      { year: "8", saving: 500 },
      { year: "9", saving: 625 },
      { year: "10", saving: 750 },
      { year: "11", saving: 875 },
      { year: "12", saving: 1000 },
      { year: "13", saving: 1125 },
      { year: "14", saving: 1250 },
      { year: "15", saving: 1375 },
    ]}
    x="year"
    y="saving"
    format={{ style: "currency", currency: "GBP", maximumFractionDigits: 0, signDisplay: "exceptZero" }}
    area
    title="After 15 years the heat pump has cost £1,375 less than the boiler"
    subtitle="Cumulative saving of a heat pump over a gas boiler in pounds, by years since installation. Includes purchase after the £7,500 grant, energy and servicing"
    annotations={[
      {
        type: "line",
        axis: "y",
        value: 0,
        label: "Same cost as the boiler",
        dashed: false,
        emphasis: true,
      },
      { type: "point", x: "4", y: 0, label: "Break-even", position: "top" },
    ]}
  />}
  heroText="Without the grant the heat pump costs £11,000 to buy and fit. That is £8,000 more than the boiler. A saving of £125 a year would take 64 years to repay it."
  pairs={[
    {
      title: "The January energy bill is £142 for the heat pump and £158 for the boiler",
      text: "Estimated monthly energy cost for heating and hot water. Both charts use the same scale. The heat pump's bill is lower in all 12 months.",
      a: <BarChart
        data={[
          { month: "Jan", cost: 142 },
          { month: "Feb", cost: 128 },
          { month: "Mar", cost: 102 },
          { month: "Apr", cost: 68 },
          { month: "May", cost: 40 },
          { month: "Jun", cost: 28 },
          { month: "Jul", cost: 25 },
          { month: "Aug", cost: 26 },
          { month: "Sep", cost: 38 },
          { month: "Oct", cost: 66 },
          { month: "Nov", cost: 98 },
          { month: "Dec", cost: 134 },
        ]}
        x="month"
        y="cost"
        orientation="vertical"
        sort="none"
        labels={false}
        format="currency:GBP"
        height={200}
        option={{ yAxis: { max: 160 } }}
      />,
      b: <BarChart
        data={[
          { month: "Jan", cost: 158 },
          { month: "Feb", cost: 141 },
          { month: "Mar", cost: 115 },
          { month: "Apr", cost: 78 },
          { month: "May", cost: 49 },
          { month: "Jun", cost: 37 },
          { month: "Jul", cost: 34 },
          { month: "Aug", cost: 35 },
          { month: "Sep", cost: 46 },
          { month: "Oct", cost: 74 },
          { month: "Nov", cost: 107 },
          { month: "Dec", cost: 146 },
        ]}
        x="month"
        y="cost"
        orientation="vertical"
        sort="none"
        labels={false}
        format="currency:GBP"
        height={200}
        highlight="none"
        option={{ yAxis: { max: 160 } }}
      />,
    },
    {
      title: "Cost over 15 years by part",
      text: "Energy is £12,075 of the heat pump's cost. It is £13,500 of the boiler's.",
      a: <SegmentedBar
        data={[
          { part: "Purchase and fitting", gbp: 3500 },
          { part: "Energy", gbp: 12075 },
          { part: "Servicing", gbp: 1500 },
        ]}
        name="part"
        value="gbp"
        format="currency:GBP"
      />,
      b: <SegmentedBar
        data={[
          { part: "Purchase and fitting", gbp: 3000 },
          { part: "Energy", gbp: 13500 },
          { part: "Servicing", gbp: 1200 },
        ]}
        name="part"
        value="gbp"
        format="currency:GBP"
      />,
    },
  ]}
  verdict={{
    lead: "Choose the heat pump if you get the grant and will stay at least 5 years",
    body: "Without the grant the boiler is cheaper. The figures assume electricity and gas prices stay at their Q4 2024 levels.",
  }}
  sources={["Energy regulator price cap, Q4 2024", "Installer quotes collected by the author"]}
  method="A house using 11,500 kWh of heat a year. Heat pump seasonal efficiency is 3.2. Boiler efficiency is 90%. Prices held flat in real terms."
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "comparison-brief",
  "kicker": "Home heating",
  "title": "With the £7,500 grant, a heat pump repays its extra £500 cost in 4 years",
  "deck": "After the grant a heat pump costs £3,500 to buy and fit. A gas boiler costs £3,000. The heat pump costs £855 a year to run. The boiler costs £980.",
  "a": { "name": "Heat pump", "detail": "Air source, 7 kW" },
  "b": { "name": "Gas boiler", "detail": "Condensing combi, 30 kW" },
  "figures": [
    {
      "label": "Cost to buy and fit, after grant",
      "a": 3500,
      "b": 3000,
      "format": { "style": "currency", "currency": "GBP", "maximumFractionDigits": 0 },
      "better": "lower"
    },
    {
      "label": "Running cost per year",
      "a": 855,
      "b": 980,
      "format": "currency:GBP",
      "better": "lower"
    },
    {
      "label": "CO2 per year, tonnes",
      "a": 0.6,
      "b": 2.3,
      "format": "decimal:1",
      "better": "lower"
    },
    {
      "label": "Heat out per unit of energy in",
      "a": 3.2,
      "b": 0.9,
      "format": "decimal:1",
      "better": "higher"
    },
    { "label": "Expected life, years", "a": 20, "b": 15, "better": "higher" }
  ],
  "hero": {
    "type": "line-chart",
    "data": [
      { "year": "0", "saving": -500 },
      { "year": "1", "saving": -375 },
      { "year": "2", "saving": -250 },
      { "year": "3", "saving": -125 },
      { "year": "4", "saving": 0 },
      { "year": "5", "saving": 125 },
      { "year": "6", "saving": 250 },
      { "year": "7", "saving": 375 },
      { "year": "8", "saving": 500 },
      { "year": "9", "saving": 625 },
      { "year": "10", "saving": 750 },
      { "year": "11", "saving": 875 },
      { "year": "12", "saving": 1000 },
      { "year": "13", "saving": 1125 },
      { "year": "14", "saving": 1250 },
      { "year": "15", "saving": 1375 }
    ],
    "x": "year",
    "y": "saving",
    "format": {
      "style": "currency",
      "currency": "GBP",
      "maximumFractionDigits": 0,
      "signDisplay": "exceptZero"
    },
    "area": true,
    "title": "After 15 years the heat pump has cost £1,375 less than the boiler",
    "subtitle": "Cumulative saving of a heat pump over a gas boiler in pounds, by years since installation. Includes purchase after the £7,500 grant, energy and servicing",
    "annotations": [
      {
        "type": "line",
        "axis": "y",
        "value": 0,
        "label": "Same cost as the boiler",
        "dashed": false,
        "emphasis": true
      },
      { "type": "point", "x": "4", "y": 0, "label": "Break-even", "position": "top" }
    ]
  },
  "heroText": "Without the grant the heat pump costs £11,000 to buy and fit. That is £8,000 more than the boiler. A saving of £125 a year would take 64 years to repay it.",
  "pairs": [
    {
      "title": "The January energy bill is £142 for the heat pump and £158 for the boiler",
      "text": "Estimated monthly energy cost for heating and hot water. Both charts use the same scale. The heat pump's bill is lower in all 12 months.",
      "a": {
        "type": "bar-chart",
        "data": [
          { "month": "Jan", "cost": 142 },
          { "month": "Feb", "cost": 128 },
          { "month": "Mar", "cost": 102 },
          { "month": "Apr", "cost": 68 },
          { "month": "May", "cost": 40 },
          { "month": "Jun", "cost": 28 },
          { "month": "Jul", "cost": 25 },
          { "month": "Aug", "cost": 26 },
          { "month": "Sep", "cost": 38 },
          { "month": "Oct", "cost": 66 },
          { "month": "Nov", "cost": 98 },
          { "month": "Dec", "cost": 134 }
        ],
        "x": "month",
        "y": "cost",
        "orientation": "vertical",
        "sort": "none",
        "labels": false,
        "format": "currency:GBP",
        "height": 200,
        "option": { "yAxis": { "max": 160 } }
      },
      "b": {
        "type": "bar-chart",
        "data": [
          { "month": "Jan", "cost": 158 },
          { "month": "Feb", "cost": 141 },
          { "month": "Mar", "cost": 115 },
          { "month": "Apr", "cost": 78 },
          { "month": "May", "cost": 49 },
          { "month": "Jun", "cost": 37 },
          { "month": "Jul", "cost": 34 },
          { "month": "Aug", "cost": 35 },
          { "month": "Sep", "cost": 46 },
          { "month": "Oct", "cost": 74 },
          { "month": "Nov", "cost": 107 },
          { "month": "Dec", "cost": 146 }
        ],
        "x": "month",
        "y": "cost",
        "orientation": "vertical",
        "sort": "none",
        "labels": false,
        "format": "currency:GBP",
        "height": 200,
        "highlight": "none",
        "option": { "yAxis": { "max": 160 } }
      }
    },
    {
      "title": "Cost over 15 years by part",
      "text": "Energy is £12,075 of the heat pump's cost. It is £13,500 of the boiler's.",
      "a": {
        "type": "segmented-bar",
        "data": [
          { "part": "Purchase and fitting", "gbp": 3500 },
          { "part": "Energy", "gbp": 12075 },
          { "part": "Servicing", "gbp": 1500 }
        ],
        "name": "part",
        "value": "gbp",
        "format": "currency:GBP"
      },
      "b": {
        "type": "segmented-bar",
        "data": [
          { "part": "Purchase and fitting", "gbp": 3000 },
          { "part": "Energy", "gbp": 13500 },
          { "part": "Servicing", "gbp": 1200 }
        ],
        "name": "part",
        "value": "gbp",
        "format": "currency:GBP"
      }
    }
  ],
  "verdict": {
    "lead": "Choose the heat pump if you get the grant and will stay at least 5 years",
    "body": "Without the grant the boiler is cheaper. The figures assume electricity and gas prices stay at their Q4 2024 levels."
  },
  "sources": ["Energy regulator price cap, Q4 2024", "Installer quotes collected by the author"],
  "method": "A house using 11,500 kWh of heat a year. Heat pump seasonal efficiency is 3.2. Boiler efficiency is 90%. Prices held flat in real terms.",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The result of the comparison, as one plain sentence with the number in it. |
| `kicker` | `string` |  | Small label above the title. |
| `deck` | `string` |  | One-sentence standfirst. |
| `byline` | `string` |  | Author line. |
| `date` | `string` |  | Publication date. |
| `a` (required) | `string \| { name, detail? }` |  | Side A, shown on the left. |
| `b` (required) | `string \| { name, detail? }` |  | Side B, shown on the right. |
| `subject` | `"a" \| "b" \| "none"` | `"a"` | The side the piece is about. It takes the accent colour; the other stays grey. Match it with `highlight` in the charts. |
| `figures` | `{ label, a, b, format?, better?: "higher" \| "lower" }[]` |  | Headline measures. Numeric values get mirrored bars scaled within each row; `better` sets the stronger value bolder. |
| `hero` | `Slot` |  | The exhibit that shows both sides at once. Default height 360px. |
| `heroText` | `string` |  | One or two sentences under the hero. |
| `pairs` | `{ title, text?, a: Slot, b: Slot }[]` |  | Paired exhibits under one heading. A is on the left and B on the right; they stack in narrow containers. Use the same form and scale for both. |
| `verdict` | `{ lead?, body?, label?, tone? }` |  | The closing recommendation, shown as a callout. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `maxWidth` | `number \| string` |  | Widest the piece may get. It is centred in wider containers. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [prose](https://insightcharts.dev/llms/prose.md), [callout](https://insightcharts.dev/llms/callout.md), [source-note](https://insightcharts.dev/llms/source-note.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [segmented-bar](https://insightcharts.dev/llms/segmented-bar.md)
- Used by: no molecule or template yet

### More examples

#### Transport: a stacked hero, no pairs

```tsx
import { BarChart, ComparisonBrief } from "insightcharts";

<ComparisonBrief
  kicker="London to Edinburgh"
  title="Flying from London to Edinburgh is 35 minutes faster than the train, door to door"
  deck="The plane takes 275 minutes and the train 310. The flight itself lasts 80 minutes. The plane emits 140 kg of CO2 per passenger. The train emits 13 kg."
  a="Train"
  b="Plane"
  figures={[
    { label: "Door to door, minutes", a: 310, b: 275, better: "lower" },
    { label: "CO2 per passenger, kg", a: 13, b: 140, better: "lower" },
    {
      label: "Typical fare booked two weeks ahead",
      a: 78,
      b: 92,
      format: "currency:GBP",
      better: "lower",
    },
    { label: "Minutes you can spend working", a: 240, b: 50, better: "higher" },
  ]}
  hero={<BarChart
    data={[
      {
        mode: "Train",
        "Getting there": 25,
        "Waiting and boarding": 15,
        "In transit": 260,
        Onward: 10,
      },
      {
        mode: "Plane",
        "Getting there": 55,
        "Waiting and boarding": 95,
        "In transit": 80,
        Onward: 45,
      },
    ]}
    x="mode"
    y={["Getting there", "Waiting and boarding", "In transit", "Onward"]}
    stack
    orientation="horizontal"
    sort="none"
    format="{value} min"
    title="80 of the plane's 275 minutes are spent in the air"
    subtitle="Minutes per stage, city centre to city centre"
    source="Timetables and airport guidance, weekday morning departures"
  />}
  verdict={{
    lead: "Take the train unless you need the 35 minutes",
    body: "The train fare is £78 and the plane fare is £92. The train gives 240 minutes of working time. The plane gives 50.",
    tone: "positive",
  }}
  sources={["Operator timetables", "Government greenhouse gas conversion factors"]}
  note="Illustrative fares and times"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/comparison-brief.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/comparison-brief.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Count poster (`count-poster`)

> A poster that counts at scale. Blocks of thousands of unit icons fill most of the sheet, a second band counts reference groups with the same icon at the same size in a muted colour, and a bottom row holds three small graphics: squares sized by area with a ratio bracket, thick bars with the numbers inside, and shares as nested outlines or filled silhouettes.

- Component: `CountPoster` (import from `insightcharts`)
- Spec type: `"count-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when the subject is a large count of people or things in 2 to 6 groups and the reader should see the crowd: pupils by stage, trees planted by species, vehicles built by model. Give `hero` the groups and `reference` one to three quantities to compare them with. Both bands use the same `unit`, `icon` and icon size, so their areas compare. State the total in the title.

### Avoid

Counts under a few hundred (use `pictogram-chart` in a `poster`). Shares of one whole as the main point (use `waffle-chart` or `treemap`). A ranking of many named things (use `ranking-poster`). A flow from sources to destinations (use `flow-poster`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/count-poster
```

The file lands at `components/insightcharts/templates/count-poster.tsx`. `@insightcharts/count-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { CountPoster } from "insightcharts";

<CountPoster
  theme="noir"
  kicker="Education"
  title="Norland's schools taught 1.84 million pupils in 2025"
  subtitle="Pupils enrolled in state schools by stage, autumn term 2025."
  unit={1000}
  unitLabel="1,000 people"
  icon="person"
  hero={{
    data: [
      { stage: "Primary", pupils: 820000 },
      { stage: "Lower secondary", pupils: 460000 },
      { stage: "Upper secondary", pupils: 390000 },
      { stage: "Vocational", pupils: 170000 },
    ],
    name: "stage",
    value: "pupils",
    title: "820,000 pupils were in primary school",
  }}
  reference={{
    data: [
      { group: "Teachers", people: 142000 },
      { group: "Support staff", people: 61000 },
      { group: "Pupils who left without a certificate", people: 38000 },
    ],
    name: "group",
    value: "people",
    title: "142,000 teachers taught them",
  }}
  area={{
    data: [
      { school: "Largest secondary school", pupils: 3640 },
      { school: "Median primary school", pupils: 280 },
    ],
    name: "school",
    value: "pupils",
    title: "The largest school had 3,640 pupils",
  }}
  bars={{
    data: [
      { year: "2000", m: 1.42 },
      { year: "2005", m: 1.51 },
      { year: "2010", m: 1.6 },
      { year: "2015", m: 1.69 },
      { year: "2020", m: 1.77 },
      { year: "2025", m: 1.84 },
    ],
    name: "year",
    value: "m",
    format: "{value}m",
    title: "Enrolment was 1.42 million in 2000",
  }}
  shares={{
    data: [
      { year: "2013", share: 6 },
      { year: "2017", share: 19 },
      { year: "2021", share: 44 },
      { year: "2025", share: 68 },
    ],
    name: "year",
    value: "share",
    highlight: "2025",
    wholeLabel: "All pupils",
    title: "68% of pupils had a school laptop in 2025",
  }}
  sources="Norland Ministry of Education, school census 2025"
  note="Norland is an invented country. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "count-poster",
  "theme": "noir",
  "kicker": "Education",
  "title": "Norland's schools taught 1.84 million pupils in 2025",
  "subtitle": "Pupils enrolled in state schools by stage, autumn term 2025.",
  "unit": 1000,
  "unitLabel": "1,000 people",
  "icon": "person",
  "hero": {
    "data": [
      { "stage": "Primary", "pupils": 820000 },
      { "stage": "Lower secondary", "pupils": 460000 },
      { "stage": "Upper secondary", "pupils": 390000 },
      { "stage": "Vocational", "pupils": 170000 }
    ],
    "name": "stage",
    "value": "pupils",
    "title": "820,000 pupils were in primary school"
  },
  "reference": {
    "data": [
      { "group": "Teachers", "people": 142000 },
      { "group": "Support staff", "people": 61000 },
      { "group": "Pupils who left without a certificate", "people": 38000 }
    ],
    "name": "group",
    "value": "people",
    "title": "142,000 teachers taught them"
  },
  "area": {
    "data": [
      { "school": "Largest secondary school", "pupils": 3640 },
      { "school": "Median primary school", "pupils": 280 }
    ],
    "name": "school",
    "value": "pupils",
    "title": "The largest school had 3,640 pupils"
  },
  "bars": {
    "data": [
      { "year": "2000", "m": 1.42 },
      { "year": "2005", "m": 1.51 },
      { "year": "2010", "m": 1.6 },
      { "year": "2015", "m": 1.69 },
      { "year": "2020", "m": 1.77 },
      { "year": "2025", "m": 1.84 }
    ],
    "name": "year",
    "value": "m",
    "format": "{value}m",
    "title": "Enrolment was 1.42 million in 2000"
  },
  "shares": {
    "data": [
      { "year": "2013", "share": 6 },
      { "year": "2017", "share": 19 },
      { "year": "2021", "share": 44 },
      { "year": "2025", "share": 68 }
    ],
    "name": "year",
    "value": "share",
    "highlight": "2025",
    "wholeLabel": "All pupils",
    "title": "68% of pupils had a school laptop in 2025"
  },
  "sources": "Norland Ministry of Education, school census 2025",
  "note": "Norland is an invented country. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `hero` (required) | `{ data, name, value, title?, subtitle?, source?, ...unit-blocks props } \| Slot` |  | The hero band: one block of unit icons per row, drawn by `unit-blocks`. A full spec or element replaces it. |
| `unit` | `number` |  | Units one icon stands for, in both bands. Default: a round number that gives the hero about 2,000 icons. |
| `unitLabel` | `string` |  | What one icon stands for, e.g. "1,000 pupils". Printed as the key of both bands. |
| `icon` | `IconName \| "path://..."` | `"person"` | Icon of both bands. |
| `format` | `FormatSpec` | `"integer"` | How to print the counts. |
| `reference` | `{ data, name, value, title?, ... } \| Slot` |  | The second band: reference groups counted with the same icon at the same size, painted in the theme's context grey (`unit-blocks`). |
| `area` | `{ data, name, value, ratio?, title?, ... } \| Slot` |  | Bottom left: two to four values as squares sized by area, with a bracket stating how many times the largest is the smallest (`proportional-area`). `ratio` defaults to `"{ratio}x larger"`. |
| `bars` | `{ data, name, value, title?, ... } \| Slot` |  | Bottom middle: 3 to 8 values as thick rounded bars with the numbers inside (`block-bar`). |
| `shares` | `{ data, name, value, icon?, title?, ... } \| Slot` |  | Bottom right: shares of one whole. With `icon` each share is a silhouette filled to its level (`shape-fill`); without, the shares are outlines nested in one square (`nested-shares`). |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"noir"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `1100` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [unit-blocks](https://insightcharts.dev/llms/unit-blocks.md), [proportional-area](https://insightcharts.dev/llms/proportional-area.md), [block-bar](https://insightcharts.dev/llms/block-bar.md), [nested-shares](https://insightcharts.dev/llms/nested-shares.md), [shape-fill](https://insightcharts.dev/llms/shape-fill.md)
- Used by: no molecule or template yet

### More examples

#### Forest, trees planted, with download

```tsx
import { CountPoster } from "insightcharts";

<CountPoster
  theme="forest"
  download
  kicker="Forestry"
  title="Foresters planted 2.4 million trees in the Aldern Valley from 2016 to 2025"
  subtitle="Trees planted by species, and trees lost over the same ten years."
  unit={1000}
  unitLabel="1,000 trees"
  icon="tree"
  hero={{
    data: [
      { species: "Oak", trees: 780000 },
      { species: "Birch", trees: 640000 },
      { species: "Scots pine", trees: 560000 },
      { species: "Alder", trees: 420000 },
    ],
    name: "species",
    value: "trees",
    title: "Oak was 780,000 of the 2.4 million trees",
  }}
  reference={{
    data: [
      { cause: "Felled for timber", trees: 310000 },
      { cause: "Lost to storms", trees: 95000 },
      { cause: "Lost to disease", trees: 64000 },
    ],
    name: "cause",
    value: "trees",
    title: "The valley lost 469,000 trees in the same years",
  }}
  area={{
    data: [{ year: "Woodland in 2025", ha: 18600 }, { year: "Planted in 2025", ha: 930 }],
    name: "year",
    value: "ha",
    format: "{value} ha",
    ratio: "{ratio}x the area",
    title: "Woodland covered 18,600 hectares in 2025",
  }}
  bars={{
    data: [
      { year: "2020", k: 180 },
      { year: "2021", k: 215 },
      { year: "2022", k: 240 },
      { year: "2023", k: 265 },
      { year: "2024", k: 290 },
      { year: "2025", k: 310 },
    ],
    name: "year",
    value: "k",
    format: "{value}k",
    title: "310,000 trees were planted in 2025",
  }}
  shares={{
    data: [{ species: "Birch", share: 92 }, { species: "Scots pine", share: 74 }],
    name: "species",
    value: "share",
    icon: "tree",
    title: "92% of birches were alive after five years",
  }}
  sources="Aldern Valley Forest Trust planting register"
  note="The Aldern Valley is an invented place. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Blueprint, bicycles built, linked panels

```tsx
import { CountPoster } from "insightcharts";

<CountPoster
  theme="blueprint"
  linked
  kicker="Manufacturing"
  title="The Orrin works built 248,000 bicycles in 2025"
  subtitle="Bicycles built by model at one factory, January to December 2025."
  unit={200}
  unitLabel="200 bicycles"
  icon="bike"
  hero={{
    data: [
      { model: "City", bikes: 96000 },
      { model: "Electric", bikes: 71000 },
      { model: "Children's", bikes: 48000 },
      { model: "Cargo", bikes: 33000 },
    ],
    name: "model",
    value: "bikes",
    title: "96,000 of the bicycles were city models",
  }}
  reference={{
    data: [
      { group: "Built in 2015", bikes: 131000 },
      { group: "Returned under warranty in 2025", bikes: 6200 },
    ],
    name: "group",
    value: "bikes",
    title: "The works built 131,000 bicycles in 2015",
  }}
  area={{
    data: [
      { year: "Electric bikes in 2025", bikes: 71000 },
      { year: "Electric bikes in 2017", bikes: 5900 },
    ],
    name: "year",
    value: "bikes",
    title: "The works built 71,000 electric bicycles in 2025",
  }}
  bars={{
    data: [
      { year: "2020", k: 162 },
      { year: "2021", k: 181 },
      { year: "2022", k: 197 },
      { year: "2023", k: 214 },
      { year: "2024", k: 231 },
      { year: "2025", k: 248 },
    ],
    name: "year",
    value: "k",
    format: "{value}k",
    title: "Output was 162,000 bicycles in 2020",
  }}
  shares={{
    data: [
      { year: "2017", share: 4 },
      { year: "2019", share: 9 },
      { year: "2021", share: 15 },
      { year: "2023", share: 22 },
      { year: "2025", share: 29 },
    ],
    name: "year",
    value: "share",
    highlight: "2025",
    wholeLabel: "All bicycles built",
    title: "Electric models were 29% of output in 2025",
  }}
  sources="Orrin Cycle Works production log"
  note="The Orrin works is an invented factory. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/count-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/count-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Data explorer (`data-explorer`)

> A set of linked charts over one shared dataset that filter each other. It has a headline, a sentence of instructions with filter chips, a row of figures that recompute from the filtered rows, two to four charts and an optional detail table. It opens on selections the author chooses.

- Component: `DataExplorer` (import from `insightcharts`)
- Spec type: `"data-explorer"`
- Level: template. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when readers will want to filter the data themselves after seeing the main finding. State the finding with its number in the headline. Set `initialSelections` so the piece opens on the view the headline describes. Use the figures and the `finding` callout to give the numbers for that view. Keep to one dataset and two to four small, plain charts. Readers click the charts to filter, so keep them all the same size.

### Avoid

A fixed message that needs no exploration (use `executive-brief` or `visual-essay`). Charts over unrelated datasets, which cannot filter each other. More than four charts or five figures.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/data-explorer
```

The file lands at `components/insightcharts/templates/data-explorer.tsx`. `@insightcharts/data-explorer-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, DataExplorer } from "insightcharts";

const data = [
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Morning",
    district: "Centre",
    trips: 198,
    minutes: 2376,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Morning",
    district: "Riverside",
    trips: 114,
    minutes: 1368,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Morning",
    district: "University",
    trips: 125,
    minutes: 1500,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Morning",
    district: "Docklands",
    trips: 83,
    minutes: 996,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Midday",
    district: "Centre",
    trips: 99,
    minutes: 1188,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Midday",
    district: "Riverside",
    trips: 57,
    minutes: 684,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Midday",
    district: "University",
    trips: 62,
    minutes: 744,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Midday",
    district: "Docklands",
    trips: 42,
    minutes: 504,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Evening",
    district: "Centre",
    trips: 213,
    minutes: 2556,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Evening",
    district: "Riverside",
    trips: 123,
    minutes: 1476,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Evening",
    district: "University",
    trips: 134,
    minutes: 1608,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Evening",
    district: "Docklands",
    trips: 90,
    minutes: 1080,
  },
  { rider: "Member", day: "Weekday", daypart: "Night", district: "Centre", trips: 46, minutes: 552 },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Night",
    district: "Riverside",
    trips: 26,
    minutes: 312,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Night",
    district: "University",
    trips: 29,
    minutes: 348,
  },
  {
    rider: "Member",
    day: "Weekday",
    daypart: "Night",
    district: "Docklands",
    trips: 19,
    minutes: 228,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Morning",
    district: "Centre",
    trips: 57,
    minutes: 684,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Morning",
    district: "Riverside",
    trips: 33,
    minutes: 396,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Morning",
    district: "University",
    trips: 36,
    minutes: 432,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Morning",
    district: "Docklands",
    trips: 24,
    minutes: 288,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Midday",
    district: "Centre",
    trips: 114,
    minutes: 1368,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Midday",
    district: "Riverside",
    trips: 66,
    minutes: 792,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Midday",
    district: "University",
    trips: 72,
    minutes: 864,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Midday",
    district: "Docklands",
    trips: 48,
    minutes: 576,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Evening",
    district: "Centre",
    trips: 84,
    minutes: 1008,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Evening",
    district: "Riverside",
    trips: 48,
    minutes: 576,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Evening",
    district: "University",
    trips: 53,
    minutes: 636,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Evening",
    district: "Docklands",
    trips: 35,
    minutes: 420,
  },
  { rider: "Member", day: "Weekend", daypart: "Night", district: "Centre", trips: 34, minutes: 408 },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Night",
    district: "Riverside",
    trips: 20,
    minutes: 240,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Night",
    district: "University",
    trips: 22,
    minutes: 264,
  },
  {
    rider: "Member",
    day: "Weekend",
    daypart: "Night",
    district: "Docklands",
    trips: 14,
    minutes: 168,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Morning",
    district: "Centre",
    trips: 18,
    minutes: 342,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Morning",
    district: "Riverside",
    trips: 24,
    minutes: 456,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Morning",
    district: "University",
    trips: 10,
    minutes: 190,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Morning",
    district: "Docklands",
    trips: 8,
    minutes: 152,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Midday",
    district: "Centre",
    trips: 54,
    minutes: 1026,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Midday",
    district: "Riverside",
    trips: 72,
    minutes: 1368,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Midday",
    district: "University",
    trips: 29,
    minutes: 551,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Midday",
    district: "Docklands",
    trips: 25,
    minutes: 475,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Evening",
    district: "Centre",
    trips: 42,
    minutes: 798,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Evening",
    district: "Riverside",
    trips: 56,
    minutes: 1064,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Evening",
    district: "University",
    trips: 22,
    minutes: 418,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Evening",
    district: "Docklands",
    trips: 20,
    minutes: 380,
  },
  { rider: "Casual", day: "Weekday", daypart: "Night", district: "Centre", trips: 15, minutes: 285 },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Night",
    district: "Riverside",
    trips: 20,
    minutes: 380,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Night",
    district: "University",
    trips: 8,
    minutes: 152,
  },
  {
    rider: "Casual",
    day: "Weekday",
    daypart: "Night",
    district: "Docklands",
    trips: 7,
    minutes: 133,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Morning",
    district: "Centre",
    trips: 27,
    minutes: 729,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Morning",
    district: "Riverside",
    trips: 36,
    minutes: 972,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Morning",
    district: "University",
    trips: 14,
    minutes: 378,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Morning",
    district: "Docklands",
    trips: 13,
    minutes: 351,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Midday",
    district: "Centre",
    trips: 156,
    minutes: 4212,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Midday",
    district: "Riverside",
    trips: 208,
    minutes: 5616,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Midday",
    district: "University",
    trips: 83,
    minutes: 2241,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Midday",
    district: "Docklands",
    trips: 73,
    minutes: 1971,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Evening",
    district: "Centre",
    trips: 93,
    minutes: 2511,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Evening",
    district: "Riverside",
    trips: 124,
    minutes: 3348,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Evening",
    district: "University",
    trips: 50,
    minutes: 1350,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Evening",
    district: "Docklands",
    trips: 43,
    minutes: 1161,
  },
  { rider: "Casual", day: "Weekend", daypart: "Night", district: "Centre", trips: 24, minutes: 648 },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Night",
    district: "Riverside",
    trips: 32,
    minutes: 864,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Night",
    district: "University",
    trips: 13,
    minutes: 351,
  },
  {
    rider: "Casual",
    day: "Weekend",
    daypart: "Night",
    district: "Docklands",
    trips: 11,
    minutes: 297,
  },
];

<DataExplorer
  kicker="City bike share · June"
  title="Casual riders' trips averaged 24.6 minutes in June, against 12.0 for members"
  deck="70% of casual trips were at weekends. 40% started in Riverside. The view below is filtered to casual riders."
  instructions="Click a bar to filter the other charts and the figures. Click it again to clear."
  finding={{
    lead: "Casual riders made 1.43 million of the 3.65 million trips in June",
    body: "520,000 of them were at weekend middays. Members made 34% of their trips at weekends.",
  }}
  data={data}
  unit="trips"
  labels={{ rider: "Rider", daypart: "Time of day", district: "District", day: "Day" }}
  initialSelections={{ "by-rider": { field: "rider", values: ["Casual"] } }}
  figures={[
    { label: "Trips, thousands", field: "trips", format: "integer" },
    { label: "Average trip length, minutes", field: "minutes", per: "trips", format: "decimal:1" },
    {
      label: "Share taken at weekends",
      field: "trips",
      where: { field: "day", value: "Weekend" },
      per: "trips",
      format: "percent",
    },
    {
      label: "Share starting in Riverside",
      field: "trips",
      where: { field: "district", value: "Riverside" },
      per: "trips",
      format: "percent",
    },
  ]}
  charts={[
    <BarChart
      id="by-rider"
      x="rider"
      y="trips"
      select
      sort="none"
      orientation="horizontal"
      format="integer"
      title="Rider"
      subtitle="Trips, thousands"
      transform={{ type: "aggregate", groupBy: "rider", measures: { trips: { op: "sum", field: "trips" } } }}
    />,
    <BarChart
      id="by-day"
      x="day"
      y="trips"
      select
      sort="none"
      orientation="horizontal"
      format="integer"
      title="Day"
      subtitle="Trips, thousands"
      transform={{ type: "aggregate", groupBy: "day", measures: { trips: { op: "sum", field: "trips" } } }}
    />,
    <BarChart
      id="by-daypart"
      x="daypart"
      y="trips"
      select
      sort="none"
      orientation="vertical"
      format="integer"
      height={220}
      title="Time of day"
      subtitle="Trips, thousands"
      transform={{ type: "aggregate", groupBy: "daypart", measures: { trips: { op: "sum", field: "trips" } } }}
    />,
    <BarChart
      id="by-district"
      x="district"
      y="trips"
      select
      sort="desc"
      orientation="horizontal"
      format="integer"
      title="Start district"
      subtitle="Trips, thousands"
      transform={{ type: "aggregate", groupBy: "district", measures: { trips: { op: "sum", field: "trips" } } }}
    />,
  ]}
  table={{
    caption: "Selected trips by start district and time of day",
    transform: [
      {
        type: "aggregate",
        groupBy: ["district", "daypart"],
        measures: { trips: { op: "sum", field: "trips" }, minutes: { op: "sum", field: "minutes" } },
      },
      { type: "derive", as: "length", op: "divide", fields: ["minutes", "trips"] },
      { type: "sort", by: "trips", order: "desc" },
      { type: "limit", n: 6 },
    ],
    columns: [
      { key: "district", label: "District" },
      { key: "daypart", label: "Time of day" },
      { key: "trips", label: "Trips, thousands", format: "integer", bar: true, width: "34%" },
      { key: "length", label: "Average minutes", format: "decimal:1" },
    ],
  }}
  sources="City bike-share operator, trip records"
  period="June 2024"
  method="A trip is a hire of more than one minute. Morning is 6 to 10am, evening 4 to 8pm."
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "data-explorer",
  "kicker": "City bike share · June",
  "title": "Casual riders' trips averaged 24.6 minutes in June, against 12.0 for members",
  "deck": "70% of casual trips were at weekends. 40% started in Riverside. The view below is filtered to casual riders.",
  "instructions": "Click a bar to filter the other charts and the figures. Click it again to clear.",
  "finding": {
    "lead": "Casual riders made 1.43 million of the 3.65 million trips in June",
    "body": "520,000 of them were at weekend middays. Members made 34% of their trips at weekends."
  },
  "data": [
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Morning",
      "district": "Centre",
      "trips": 198,
      "minutes": 2376
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Morning",
      "district": "Riverside",
      "trips": 114,
      "minutes": 1368
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Morning",
      "district": "University",
      "trips": 125,
      "minutes": 1500
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Morning",
      "district": "Docklands",
      "trips": 83,
      "minutes": 996
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Midday",
      "district": "Centre",
      "trips": 99,
      "minutes": 1188
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Midday",
      "district": "Riverside",
      "trips": 57,
      "minutes": 684
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Midday",
      "district": "University",
      "trips": 62,
      "minutes": 744
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Midday",
      "district": "Docklands",
      "trips": 42,
      "minutes": 504
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Evening",
      "district": "Centre",
      "trips": 213,
      "minutes": 2556
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Evening",
      "district": "Riverside",
      "trips": 123,
      "minutes": 1476
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Evening",
      "district": "University",
      "trips": 134,
      "minutes": 1608
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Evening",
      "district": "Docklands",
      "trips": 90,
      "minutes": 1080
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Night",
      "district": "Centre",
      "trips": 46,
      "minutes": 552
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Night",
      "district": "Riverside",
      "trips": 26,
      "minutes": 312
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Night",
      "district": "University",
      "trips": 29,
      "minutes": 348
    },
    {
      "rider": "Member",
      "day": "Weekday",
      "daypart": "Night",
      "district": "Docklands",
      "trips": 19,
      "minutes": 228
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Morning",
      "district": "Centre",
      "trips": 57,
      "minutes": 684
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Morning",
      "district": "Riverside",
      "trips": 33,
      "minutes": 396
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Morning",
      "district": "University",
      "trips": 36,
      "minutes": 432
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Morning",
      "district": "Docklands",
      "trips": 24,
      "minutes": 288
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Midday",
      "district": "Centre",
      "trips": 114,
      "minutes": 1368
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Midday",
      "district": "Riverside",
      "trips": 66,
      "minutes": 792
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Midday",
      "district": "University",
      "trips": 72,
      "minutes": 864
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Midday",
      "district": "Docklands",
      "trips": 48,
      "minutes": 576
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Evening",
      "district": "Centre",
      "trips": 84,
      "minutes": 1008
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Evening",
      "district": "Riverside",
      "trips": 48,
      "minutes": 576
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Evening",
      "district": "University",
      "trips": 53,
      "minutes": 636
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Evening",
      "district": "Docklands",
      "trips": 35,
      "minutes": 420
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Night",
      "district": "Centre",
      "trips": 34,
      "minutes": 408
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Night",
      "district": "Riverside",
      "trips": 20,
      "minutes": 240
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Night",
      "district": "University",
      "trips": 22,
      "minutes": 264
    },
    {
      "rider": "Member",
      "day": "Weekend",
      "daypart": "Night",
      "district": "Docklands",
      "trips": 14,
      "minutes": 168
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Morning",
      "district": "Centre",
      "trips": 18,
      "minutes": 342
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Morning",
      "district": "Riverside",
      "trips": 24,
      "minutes": 456
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Morning",
      "district": "University",
      "trips": 10,
      "minutes": 190
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Morning",
      "district": "Docklands",
      "trips": 8,
      "minutes": 152
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Midday",
      "district": "Centre",
      "trips": 54,
      "minutes": 1026
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Midday",
      "district": "Riverside",
      "trips": 72,
      "minutes": 1368
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Midday",
      "district": "University",
      "trips": 29,
      "minutes": 551
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Midday",
      "district": "Docklands",
      "trips": 25,
      "minutes": 475
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Evening",
      "district": "Centre",
      "trips": 42,
      "minutes": 798
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Evening",
      "district": "Riverside",
      "trips": 56,
      "minutes": 1064
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Evening",
      "district": "University",
      "trips": 22,
      "minutes": 418
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Evening",
      "district": "Docklands",
      "trips": 20,
      "minutes": 380
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Night",
      "district": "Centre",
      "trips": 15,
      "minutes": 285
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Night",
      "district": "Riverside",
      "trips": 20,
      "minutes": 380
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Night",
      "district": "University",
      "trips": 8,
      "minutes": 152
    },
    {
      "rider": "Casual",
      "day": "Weekday",
      "daypart": "Night",
      "district": "Docklands",
      "trips": 7,
      "minutes": 133
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Morning",
      "district": "Centre",
      "trips": 27,
      "minutes": 729
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Morning",
      "district": "Riverside",
      "trips": 36,
      "minutes": 972
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Morning",
      "district": "University",
      "trips": 14,
      "minutes": 378
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Morning",
      "district": "Docklands",
      "trips": 13,
      "minutes": 351
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Midday",
      "district": "Centre",
      "trips": 156,
      "minutes": 4212
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Midday",
      "district": "Riverside",
      "trips": 208,
      "minutes": 5616
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Midday",
      "district": "University",
      "trips": 83,
      "minutes": 2241
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Midday",
      "district": "Docklands",
      "trips": 73,
      "minutes": 1971
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Evening",
      "district": "Centre",
      "trips": 93,
      "minutes": 2511
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Evening",
      "district": "Riverside",
      "trips": 124,
      "minutes": 3348
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Evening",
      "district": "University",
      "trips": 50,
      "minutes": 1350
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Evening",
      "district": "Docklands",
      "trips": 43,
      "minutes": 1161
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Night",
      "district": "Centre",
      "trips": 24,
      "minutes": 648
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Night",
      "district": "Riverside",
      "trips": 32,
      "minutes": 864
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Night",
      "district": "University",
      "trips": 13,
      "minutes": 351
    },
    {
      "rider": "Casual",
      "day": "Weekend",
      "daypart": "Night",
      "district": "Docklands",
      "trips": 11,
      "minutes": 297
    }
  ],
  "unit": "trips",
  "labels": { "rider": "Rider", "daypart": "Time of day", "district": "District", "day": "Day" },
  "initialSelections": { "by-rider": { "field": "rider", "values": ["Casual"] } },
  "figures": [
    { "label": "Trips, thousands", "field": "trips", "format": "integer" },
    {
      "label": "Average trip length, minutes",
      "field": "minutes",
      "per": "trips",
      "format": "decimal:1"
    },
    {
      "label": "Share taken at weekends",
      "field": "trips",
      "where": { "field": "day", "value": "Weekend" },
      "per": "trips",
      "format": "percent"
    },
    {
      "label": "Share starting in Riverside",
      "field": "trips",
      "where": { "field": "district", "value": "Riverside" },
      "per": "trips",
      "format": "percent"
    }
  ],
  "charts": [
    {
      "type": "bar-chart",
      "id": "by-rider",
      "x": "rider",
      "y": "trips",
      "select": true,
      "sort": "none",
      "orientation": "horizontal",
      "format": "integer",
      "title": "Rider",
      "subtitle": "Trips, thousands",
      "transform": {
        "type": "aggregate",
        "groupBy": "rider",
        "measures": { "trips": { "op": "sum", "field": "trips" } }
      }
    },
    {
      "type": "bar-chart",
      "id": "by-day",
      "x": "day",
      "y": "trips",
      "select": true,
      "sort": "none",
      "orientation": "horizontal",
      "format": "integer",
      "title": "Day",
      "subtitle": "Trips, thousands",
      "transform": {
        "type": "aggregate",
        "groupBy": "day",
        "measures": { "trips": { "op": "sum", "field": "trips" } }
      }
    },
    {
      "type": "bar-chart",
      "id": "by-daypart",
      "x": "daypart",
      "y": "trips",
      "select": true,
      "sort": "none",
      "orientation": "vertical",
      "format": "integer",
      "height": 220,
      "title": "Time of day",
      "subtitle": "Trips, thousands",
      "transform": {
        "type": "aggregate",
        "groupBy": "daypart",
        "measures": { "trips": { "op": "sum", "field": "trips" } }
      }
    },
    {
      "type": "bar-chart",
      "id": "by-district",
      "x": "district",
      "y": "trips",
      "select": true,
      "sort": "desc",
      "orientation": "horizontal",
      "format": "integer",
      "title": "Start district",
      "subtitle": "Trips, thousands",
      "transform": {
        "type": "aggregate",
        "groupBy": "district",
        "measures": { "trips": { "op": "sum", "field": "trips" } }
      }
    }
  ],
  "table": {
    "caption": "Selected trips by start district and time of day",
    "transform": [
      {
        "type": "aggregate",
        "groupBy": ["district", "daypart"],
        "measures": {
          "trips": { "op": "sum", "field": "trips" },
          "minutes": { "op": "sum", "field": "minutes" }
        }
      },
      { "type": "derive", "as": "length", "op": "divide", "fields": ["minutes", "trips"] },
      { "type": "sort", "by": "trips", "order": "desc" },
      { "type": "limit", "n": 6 }
    ],
    "columns": [
      { "key": "district", "label": "District" },
      { "key": "daypart", "label": "Time of day" },
      {
        "key": "trips",
        "label": "Trips, thousands",
        "format": "integer",
        "bar": true,
        "width": "34%"
      },
      { "key": "length", "label": "Average minutes", "format": "decimal:1" }
    ]
  },
  "sources": "City bike-share operator, trip records",
  "period": "June 2024",
  "method": "A trip is a hire of more than one minute. Morning is 6 to 10am, evening 4 to 8pm.",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | What the starting view shows, as one plain sentence with the number in it. |
| `kicker` | `string` |  | Small label above the title. |
| `deck` | `string` |  | One-sentence standfirst. |
| `byline` | `string` |  | Author line. |
| `date` | `string` |  | Publication date. |
| `instructions` | `string` |  | One sentence saying what can be clicked and what happens. Shown in the filter line. |
| `finding` | `{ lead?, body?, label? }` |  | A callout saying what to look for in the starting view. |
| `data` (required) | `DataInput` |  | The shared, row-level dataset: rows, CSV text, a URL or a loader. |
| `transform` | `Transform \| Transform[]` |  | Applied once to the shared data. |
| `charts` (required) | `Slot[]` |  | Two to four chart specs. Give each a stable `id`, `select: true` (or a field name) and its own aggregating `transform`; leave out `data`. |
| `initialSelections` | `Record<string, { field, values?, range? }>` |  | Selections the piece opens with, keyed by chart `id`. A button restores them after the reader changes the filter. |
| `figures` | `{ label, field?, op?, where?: { field, value }, per?, format?, context? }[]` |  | Figures recomputed from the filtered rows: `op` over `field` (default sum; count without a field), optionally restricted by `where` and divided by the sum of `per` for a rate or share. While a filter is active each shows the all-rows value as context. |
| `table` | `{ transform?, columns?, caption?, sort?, highlight?, ... }` |  | A detail table of the filtered rows: the props of `data-table` without `rows`, plus a `transform` applied first. |
| `labels` | `Record<string, string>` |  | Display names for fields in the filter chips. |
| `unit` | `string` | `"rows"` | Noun for what the figures total, used in figure context ("3,650 across all trips"). |
| `count` | `boolean` | `false` | Show the filtered row count beside the chips. |
| `rowUnit` | `string` | `"rows"` | Noun for one row of `data` in that count. |
| `columns` | `number` |  | Preferred chart columns. |
| `restoreLabel` | `string` | `"Back to the starting view"` | Label of the button that restores `initialSelections`. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `maxWidth` | `number \| string` |  | Widest the piece may get. It is centred in wider containers. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [callout](https://insightcharts.dev/llms/callout.md), [filter-chips](https://insightcharts.dev/llms/filter-chips.md), [stat-row](https://insightcharts.dev/llms/stat-row.md), [linked-charts](https://insightcharts.dev/llms/linked-charts.md), [data-table](https://insightcharts.dev/llms/data-table.md), [source-note](https://insightcharts.dev/llms/source-note.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md)
- Used by: no molecule or template yet

### More examples

#### Education: rates rather than totals, two starting filters

```tsx
import { BarChart, DataExplorer } from "insightcharts";

const data = [
  { phase: "Primary", meals: "Eligible", term: "Autumn", sessions: 410, missed: 31.16 },
  { phase: "Primary", meals: "Eligible", term: "Spring", sessions: 410, missed: 34.44 },
  { phase: "Primary", meals: "Eligible", term: "Summer", sessions: 410, missed: 33.21 },
  { phase: "Primary", meals: "Not eligible", term: "Autumn", sessions: 1320, missed: 60.72 },
  { phase: "Primary", meals: "Not eligible", term: "Spring", sessions: 1320, missed: 68.64 },
  { phase: "Primary", meals: "Not eligible", term: "Summer", sessions: 1320, missed: 64.68 },
  { phase: "Secondary", meals: "Eligible", term: "Autumn", sessions: 300, missed: 39.3 },
  { phase: "Secondary", meals: "Eligible", term: "Spring", sessions: 300, missed: 43.8 },
  // ... 10 more rows
];

<DataExplorer
  kicker="School attendance · 2023/24"
  title="Secondary pupils on free school meals missed 14.5% of sessions in 2023/24"
  deck="The rate for all pupils was 7.2%. For secondary pupils on free school meals it was 13.1% in the autumn term and 15.8% in the summer term."
  instructions="Click a bar to filter the other charts and the figures. The bars show absence rates, not totals."
  data={data}
  unit="pupil groups"
  labels={{ phase: "School type", meals: "Free school meals", term: "Term" }}
  initialSelections={{
    "by-phase": { field: "phase", values: ["Secondary"] },
    "by-meals": { field: "meals", values: ["Eligible"] },
  }}
  figures={[
    {
      label: "Absence rate",
      field: "missed",
      per: "sessions",
      format: { style: "percent", maximumFractionDigits: 1 },
    },
    { label: "Sessions missed, thousands", field: "missed", format: "decimal:1" },
    { label: "Sessions possible, thousands", field: "sessions", format: "integer" },
  ]}
  charts={[
    <BarChart
      id="by-phase"
      x="phase"
      y="rate"
      select
      sort="none"
      orientation="horizontal"
      format={{ style: "percent", maximumFractionDigits: 1 }}
      title="School type"
      subtitle="Absence rate"
      transform={[
        {
          type: "aggregate",
          groupBy: "phase",
          measures: { missed: { op: "sum", field: "missed" }, sessions: { op: "sum", field: "sessions" } },
        },
        { type: "derive", as: "rate", op: "divide", fields: ["missed", "sessions"] },
      ]}
    />,
    <BarChart
      id="by-meals"
      x="meals"
      y="rate"
      select
      sort="none"
      orientation="horizontal"
      format={{ style: "percent", maximumFractionDigits: 1 }}
      title="Free school meals"
      subtitle="Absence rate"
      transform={[
        {
          type: "aggregate",
          groupBy: "meals",
          measures: { missed: { op: "sum", field: "missed" }, sessions: { op: "sum", field: "sessions" } },
        },
        { type: "derive", as: "rate", op: "divide", fields: ["missed", "sessions"] },
      ]}
    />,
    <BarChart
      id="by-term"
      x="term"
      y="rate"
      select
      sort="none"
      orientation="vertical"
      format={{ style: "percent", maximumFractionDigits: 1 }}
      height={200}
      title="Term"
      subtitle="Absence rate"
      transform={[
        {
          type: "aggregate",
          groupBy: "term",
          measures: { missed: { op: "sum", field: "missed" }, sessions: { op: "sum", field: "sessions" } },
        },
        { type: "derive", as: "rate", op: "divide", fields: ["missed", "sessions"] },
      ]}
    />,
  ]}
  sources="Local authority attendance returns"
  period="School year 2023/24"
  method="A session is half a school day. The absence rate is sessions missed, authorised or not, as a share of sessions possible."
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/data-explorer.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/data-explorer.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Executive brief (`executive-brief`)

> A one-page summary. It has a headline that states the main finding with its number, a deck, a row of three or four key figures, one hero chart with a takeaway callout, two smaller supporting exhibits, a short list of actions and a source note.

- Component: `ExecutiveBrief` (import from `insightcharts`)
- Spec type: `"executive-brief"`
- Level: template. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when a decision-maker will spend about a minute on the page. State the main finding with its number and period in the headline. The headline and the hero chart should be enough for a reader who stops there. The figures, supporting exhibits and actions add detail. Use one accent colour for the subject (`highlight`) and leave everything else grey. Mark the cause on the hero as an annotation. The proportions suit a printed page.

### Avoid

More than one hero or more than three supporting exhibits (use `report-page`). A recurring set of numbers with no single finding (use `scorecard`). A story told in several steps (use `visual-essay`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/executive-brief
```

The file lands at `components/insightcharts/templates/executive-brief.tsx`. `@insightcharts/executive-brief-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, DumbbellChart, ExecutiveBrief, LineChart } from "insightcharts";

<ExecutiveBrief
  kicker="Retention review · Q4 2024"
  title="Monthly churn fell from 4.2% to 2.1% in 2024"
  deck="The new onboarding shipped in March. Accounts that joined before March still churn at 3.8% a month."
  byline="Growth analytics"
  date="2025-01-14"
  figures={[
    {
      value: "2.1%",
      label: "Monthly churn, December",
      delta: "−2.1 pts",
      deltaLabel: "vs January",
      upIsGood: false,
    },
    {
      value: 0.61,
      format: "percent",
      label: "New accounts finishing setup in week one",
      delta: "+19 pts",
      deltaLabel: "vs January",
    },
    {
      value: 1.12,
      format: "percent",
      label: "Net revenue retention",
      context: "Top quartile for the sector is 110%",
    },
    {
      value: "$1.9m",
      label: "Annual revenue retained",
      context: "Compared with churn staying at the January rate of 4.2%",
    },
  ]}
  hero={<LineChart
    data={[
      { month: "2024-01-01", churn: 4.2 },
      { month: "2024-02-01", churn: 4.3 },
      { month: "2024-03-01", churn: 4.1 },
      { month: "2024-04-01", churn: 3.6 },
      { month: "2024-05-01", churn: 3.1 },
      { month: "2024-06-01", churn: 2.9 },
      { month: "2024-07-01", churn: 2.6 },
      { month: "2024-08-01", churn: 2.4 },
      { month: "2024-09-01", churn: 2.3 },
      { month: "2024-10-01", churn: 2.2 },
      { month: "2024-11-01", churn: 2.1 },
      { month: "2024-12-01", churn: 2.1 },
    ]}
    x="month"
    y="churn"
    format="{value}%"
    zero
    title="Monthly churn fell from 4.1% in March to 2.1% in December"
    subtitle="Share of paying accounts cancelling each month, 2024"
    annotations={[
      { type: "line", axis: "x", value: "2024-03-01", label: "New onboarding ships" },
      { type: "band", axis: "y", from: 2, to: 2.5, label: "Target range" },
    ]}
    source="Billing system"
  />}
  takeaway={{
    lead: "Churn was between 2.1% and 2.4% from August to December",
    body: "The new onboarding shipped in March. Churn did not fall in the same months of 2023.",
  }}
  supporting={[
    <DumbbellChart
      data={[
        { plan: "Starter", jan: 6.1, dec: 2.9 },
        { plan: "Team", jan: 4, dec: 2 },
        { plan: "Business", jan: 2.4, dec: 1.6 },
        { plan: "Enterprise", jan: 0.9, dec: 0.8 },
      ]}
      category="plan"
      from="jan"
      to="dec"
      names={{ jan: "January", dec: "December" }}
      format="{value}%"
      sort="none"
      highlight="Starter"
      title="Starter plan churn fell from 6.1% to 2.9%"
      subtitle="Monthly churn by plan, January and December 2024"
    />,
    <BarChart
      data={[
        { reason: "Setup not finished", before: 38, after: 14 },
        { reason: "Too expensive", before: 22, after: 27 },
        { reason: "Missing a feature", before: 17, after: 24 },
        { reason: "Went to a rival", before: 13, after: 19 },
        { reason: "Company closed", before: 10, after: 16 },
      ]}
      x="reason"
      y="after"
      sort="none"
      orientation="horizontal"
      format="{value}%"
      highlight="Setup not finished"
      title="“Setup not finished” was the reason for 14% of cancellations in Q4"
      subtitle="Share of cancellations by stated reason, Q4 2024. “Setup not finished” was 38% in Q1"
    />,
  ]}
  actions={[
    {
      title: "Offer the guided setup to the 2,400 accounts that joined before March",
      text: "These accounts churn at 3.8% a month.",
      owner: "Lifecycle · by end of February",
    },
    {
      title: "Make the setup checklist the default on the Team plan",
      text: "The checklist is opt-in on Team today. Team churn was 2.0% in December.",
      owner: "Product · Q1",
    },
    {
      title: "Measure churn again in March 2025",
      text: "That will give 12 months of data since the new onboarding shipped.",
      owner: "Growth analytics",
    },
  ]}
  sources={["Billing system", "Product analytics warehouse"]}
  period="January to December 2024, monthly"
  method="Churn is the share of accounts paying at the start of a month that cancel during it. Downgrades are not counted."
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "executive-brief",
  "kicker": "Retention review · Q4 2024",
  "title": "Monthly churn fell from 4.2% to 2.1% in 2024",
  "deck": "The new onboarding shipped in March. Accounts that joined before March still churn at 3.8% a month.",
  "byline": "Growth analytics",
  "date": "2025-01-14",
  "figures": [
    {
      "value": "2.1%",
      "label": "Monthly churn, December",
      "delta": "−2.1 pts",
      "deltaLabel": "vs January",
      "upIsGood": false
    },
    {
      "value": 0.61,
      "format": "percent",
      "label": "New accounts finishing setup in week one",
      "delta": "+19 pts",
      "deltaLabel": "vs January"
    },
    {
      "value": 1.12,
      "format": "percent",
      "label": "Net revenue retention",
      "context": "Top quartile for the sector is 110%"
    },
    {
      "value": "$1.9m",
      "label": "Annual revenue retained",
      "context": "Compared with churn staying at the January rate of 4.2%"
    }
  ],
  "hero": {
    "type": "line-chart",
    "data": [
      { "month": "2024-01-01", "churn": 4.2 },
      { "month": "2024-02-01", "churn": 4.3 },
      { "month": "2024-03-01", "churn": 4.1 },
      { "month": "2024-04-01", "churn": 3.6 },
      { "month": "2024-05-01", "churn": 3.1 },
      { "month": "2024-06-01", "churn": 2.9 },
      { "month": "2024-07-01", "churn": 2.6 },
      { "month": "2024-08-01", "churn": 2.4 },
      { "month": "2024-09-01", "churn": 2.3 },
      { "month": "2024-10-01", "churn": 2.2 },
      { "month": "2024-11-01", "churn": 2.1 },
      { "month": "2024-12-01", "churn": 2.1 }
    ],
    "x": "month",
    "y": "churn",
    "format": "{value}%",
    "zero": true,
    "title": "Monthly churn fell from 4.1% in March to 2.1% in December",
    "subtitle": "Share of paying accounts cancelling each month, 2024",
    "annotations": [
      { "type": "line", "axis": "x", "value": "2024-03-01", "label": "New onboarding ships" },
      { "type": "band", "axis": "y", "from": 2, "to": 2.5, "label": "Target range" }
    ],
    "source": "Billing system"
  },
  "takeaway": {
    "lead": "Churn was between 2.1% and 2.4% from August to December",
    "body": "The new onboarding shipped in March. Churn did not fall in the same months of 2023."
  },
  "supporting": [
    {
      "type": "dumbbell-chart",
      "data": [
        { "plan": "Starter", "jan": 6.1, "dec": 2.9 },
        { "plan": "Team", "jan": 4, "dec": 2 },
        { "plan": "Business", "jan": 2.4, "dec": 1.6 },
        { "plan": "Enterprise", "jan": 0.9, "dec": 0.8 }
      ],
      "category": "plan",
      "from": "jan",
      "to": "dec",
      "names": { "jan": "January", "dec": "December" },
      "format": "{value}%",
      "sort": "none",
      "highlight": "Starter",
      "title": "Starter plan churn fell from 6.1% to 2.9%",
      "subtitle": "Monthly churn by plan, January and December 2024"
    },
    {
      "type": "bar-chart",
      "data": [
        { "reason": "Setup not finished", "before": 38, "after": 14 },
        { "reason": "Too expensive", "before": 22, "after": 27 },
        { "reason": "Missing a feature", "before": 17, "after": 24 },
        { "reason": "Went to a rival", "before": 13, "after": 19 },
        { "reason": "Company closed", "before": 10, "after": 16 }
      ],
      "x": "reason",
      "y": "after",
      "sort": "none",
      "orientation": "horizontal",
      "format": "{value}%",
      "highlight": "Setup not finished",
      "title": "“Setup not finished” was the reason for 14% of cancellations in Q4",
      "subtitle": "Share of cancellations by stated reason, Q4 2024. “Setup not finished” was 38% in Q1"
    }
  ],
  "actions": [
    {
      "title": "Offer the guided setup to the 2,400 accounts that joined before March",
      "text": "These accounts churn at 3.8% a month.",
      "owner": "Lifecycle · by end of February"
    },
    {
      "title": "Make the setup checklist the default on the Team plan",
      "text": "The checklist is opt-in on Team today. Team churn was 2.0% in December.",
      "owner": "Product · Q1"
    },
    {
      "title": "Measure churn again in March 2025",
      "text": "That will give 12 months of data since the new onboarding shipped.",
      "owner": "Growth analytics"
    }
  ],
  "sources": ["Billing system", "Product analytics warehouse"],
  "period": "January to December 2024, monthly",
  "method": "Churn is the share of accounts paying at the start of a month that cancel during it. Downgrades are not counted.",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The main finding, as one plain sentence with the number and the period in it. |
| `kicker` | `string` |  | Small label above the title: the report series or team. |
| `deck` | `string` |  | One to three short sentences. Each states one more fact. |
| `byline` | `string` |  | Author line, shown as written. |
| `date` | `string` |  | Publication date. ISO dates are formatted for the locale. |
| `figures` | `{ value, label, context?, delta?, deltaLabel?, upIsGood?, format? }[]` |  | Three or four key figures, most important first. Rendered with `stat-row`. |
| `hero` (required) | `Slot` |  | The hero exhibit: a chart spec or element whose `title` states one fact with its number. Gets a height of 340px (260px on phones) unless it sets one. |
| `takeaway` | `{ lead?, body?, label?, tone? }` |  | The callout beside the hero. `lead` is one short sentence stating the main fact. `body` gives the supporting numbers. |
| `supporting` | `Slot[]` |  | Two (at most three) smaller exhibits shown side by side; they stack in narrow containers. Default height 220px. |
| `actions` | `(string \| { title, text?, owner? })[]` |  | Recommended actions, numbered. Two to four. |
| `actionsTitle` | `string` | `"What to do"` | Heading of the actions list. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `maxWidth` | `number \| string` |  | Widest the piece may get. It is centred in wider containers. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [stat-row](https://insightcharts.dev/llms/stat-row.md), [chart-callout](https://insightcharts.dev/llms/chart-callout.md), [prose](https://insightcharts.dev/llms/prose.md), [source-note](https://insightcharts.dev/llms/source-note.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [dumbbell-chart](https://insightcharts.dev/llms/dumbbell-chart.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md)
- Used by: no molecule or template yet

### More examples

#### Public health: emergency department waits

```tsx
import { BarChart, DumbbellChart, ExecutiveBrief, LineChart } from "insightcharts";

<ExecutiveBrief
  kicker="Urgent care board · December 2024"
  title="78.6% of emergency patients were seen within four hours in December 2024"
  deck="The share was 71.2% in January. St Anne's opened a same-day assessment unit in September. Its four-hour performance rose from 68% to 81%."
  date="2025-01-09"
  figures={[
    {
      value: "78.6%",
      label: "Seen within four hours, December",
      delta: "+7.4 pts",
      deltaLabel: "vs January",
    },
    {
      value: "4h 50m",
      label: "Median time in department for admitted patients",
      delta: "−38 min",
      deltaLabel: "vs January",
      upIsGood: false,
    },
    {
      value: 412,
      label: "Waits over twelve hours",
      delta: -0.31,
      deltaLabel: "vs January",
      upIsGood: false,
    },
  ]}
  hero={<LineChart
    data={[
      { month: "2024-01-01", within: 71.2 },
      { month: "2024-02-01", within: 70.4 },
      { month: "2024-03-01", within: 69.8 },
      { month: "2024-04-01", within: 70.9 },
      { month: "2024-05-01", within: 72.3 },
      { month: "2024-06-01", within: 73 },
      { month: "2024-07-01", within: 72.1 },
      { month: "2024-08-01", within: 71.6 },
      { month: "2024-09-01", within: 73.4 },
      { month: "2024-10-01", within: 75.8 },
      { month: "2024-11-01", within: 77.9 },
      { month: "2024-12-01", within: 78.6 },
    ]}
    x="month"
    y="within"
    format="{value}%"
    title="Four-hour performance rose from 73.4% in September to 78.6% in December"
    subtitle="Share of emergency attendances admitted, transferred or discharged within four hours, all sites, 2024"
    annotations={[
      { type: "line", axis: "x", value: "2024-09-01", label: "Assessment unit opens" },
      { type: "line", axis: "y", value: 78, label: "National standard, 78%" },
    ]}
  />}
  takeaway={{
    lead: "The 78% national standard was met in December",
    body: "Performance was 77.9% in November and 78.6% in December. It was between 69.8% and 73.4% from January to September.",
    tone: "positive",
  }}
  supporting={[
    <DumbbellChart
      data={[
        { site: "St Anne's", before: 68, after: 81 },
        { site: "Riverside", before: 72, after: 79 },
        { site: "Northgate", before: 74, after: 76 },
        { site: "Queen Mary", before: 70, after: 71 },
      ]}
      category="site"
      from="before"
      to="after"
      names={{ before: "Jan to Aug", after: "Sep to Dec" }}
      format="{value}%"
      sort="gap"
      highlight="St Anne's"
      title="St Anne's rose from 68% to 81% after its unit opened"
      subtitle="Four-hour performance by site, before and after September"
    />,
    <BarChart
      data={[
        { stage: "Arrival to triage", minutes: 14 },
        { stage: "Triage to clinician", minutes: 68 },
        { stage: "Tests and decision", minutes: 87 },
        { stage: "Waiting for a bed", minutes: 121 },
      ]}
      x="stage"
      y="minutes"
      sort="none"
      orientation="horizontal"
      format="{value} min"
      highlight="Waiting for a bed"
      title="Admitted patients waited a median of 121 minutes for a bed"
      subtitle="Median minutes per stage, admitted patients, Q4 2024"
    />,
  ]}
  actions={[
    "Open a same-day assessment unit at Riverside",
    "Fund weekend discharge teams to cut the 121-minute wait for a bed",
    "Report four-hour performance separately for each of the four sites",
  ]}
  sources="Trust emergency care dataset"
  period="January to December 2024"
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/executive-brief.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/executive-brief.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Explainer (`explainer`)

> 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.

- Component: `Explainer` (import from `insightcharts`)
- Spec type: `"explainer"`
- Level: template. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it to explain one subject to a general audience in a single narrow column. The column also works as a tall image or on a phone screen. State the main finding with its number in the headline and repeat the main number in `hook`. Make the hero exhibit the largest thing on the page. Give each numbered section one heading, one exhibit and one sentence with its main number. Write each section so it can be read without the others. Keep one accent colour on the subject (`highlight`) throughout.

### Avoid

Findings that need caveats and separate interpretation (use `report-page`). A chart that has to change step by step (use `visual-essay` with a scrolly block). More than five sections, because readers stop before the end.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/explainer
```

The file lands at `components/insightcharts/templates/explainer.tsx`. `@insightcharts/explainer-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, Explainer, IconStat } from "insightcharts";

<Explainer
  kicker="Food and climate"
  title="Households threw away 631 million tonnes of food in 2022"
  deck="That is 60% of the 1.05 billion tonnes of food wasted worldwide. Food service wasted 290 million tonnes and retail 131 million."
  hook={{
    value: 19,
    total: 100,
    text: "tonnes of food that reach shops, restaurants and homes are thrown away.",
    detail: "That was 1.05 billion tonnes in 2022.",
  }}
  hero={<BarChart
    data={[
      { sector: "Households", mt: 631 },
      { sector: "Food service", mt: 290 },
      { sector: "Retail", mt: 131 },
    ]}
    x="sector"
    y="mt"
    sort="none"
    orientation="horizontal"
    highlight="Households"
    format="{value} Mt"
    title="Households produced 60% of the world's food waste in 2022"
    subtitle="Food waste by sector, million tonnes (Mt), 2022"
    source="UNEP Food Waste Index Report 2024"
    note="Figures are approximate, for illustration"
  />}
  heroText="Food service produced 290 million tonnes, or 28%. Retail produced 131 million tonnes, or 12%."
  sections={[
    {
      title: "Household food waste by income group",
      text: "Households in high-income countries waste 81 kg of food per person a year. In upper-middle-income countries the figure is 88 kg. In lower-middle-income countries it is 86 kg.",
      exhibit: <BarChart
        data={[
          { group: "High income", kg: 81 },
          { group: "Upper-middle", kg: 88 },
          { group: "Lower-middle", kg: 86 },
        ]}
        x="group"
        y="kg"
        sort="none"
        orientation="horizontal"
        format="{value} kg"
        subtitle="Household food waste per person per year, by country income group"
      />,
      takeaway: "The three income groups are within 7 kg per person of each other.",
    },
    {
      title: "Lost and wasted food causes 4.4 billion tonnes of emissions a year",
      text: "Growing, transporting and chilling food uses land, fertiliser and fuel. Food releases methane when it rots. Lost and wasted food causes 8 to 10% of global greenhouse gas emissions.",
      exhibit: <BarChart
        data={[
          { emitter: "China", gt: 13 },
          { emitter: "United States", gt: 6 },
          { emitter: "Wasted food", gt: 4.4 },
          { emitter: "India", gt: 3.9 },
          { emitter: "European Union", gt: 3.4 },
        ]}
        x="emitter"
        y="gt"
        sort="desc"
        orientation="horizontal"
        highlight="Wasted food"
        format="{value} Gt"
        subtitle="Annual greenhouse gas emissions, billion tonnes of CO2 equivalent. Wasted food includes losses before retail"
      />,
      takeaway: "Only China and the United States emit more than lost and wasted food.",
    },
    {
      title: "733 million people faced hunger in 2023",
      exhibit: <IconStat
        icon="person"
        count={1}
        total={11}
        columns={11}
        text="people in the world faced hunger in 2023."
      />,
    },
  ]}
  conclusion={{
    title: "The UN target is to halve food waste by 2030",
    text: "Britain and Japan publish household food waste figures. Britain has cut household waste by 18% and Japan by 31%.",
    points: [
      "Measure household food waste and publish the figure every year.",
      "State on packaging that “best before” refers to quality and “use by” refers to safety.",
      "Plan meals before shopping and freeze food that will not be eaten in time.",
    ],
    action: {
      label: "Read the UNEP report",
      href: "https://www.unep.org/resources/publication/food-waste-index-report-2024",
    },
  }}
  sources={[
    {
      name: "UNEP Food Waste Index Report 2024",
      url: "https://www.unep.org/resources/publication/food-waste-index-report-2024",
    },
    "FAO, State of Food Security and Nutrition in the World 2024",
    "Emissions figures rounded from national inventories",
  ]}
  note="Figures are approximate, for illustration"
  period="2022 (waste), 2023 (hunger and emissions)"
  method="Food waste is measured at retail, food service and household level and includes inedible parts. Losses on farms and in transport are counted separately."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "explainer",
  "kicker": "Food and climate",
  "title": "Households threw away 631 million tonnes of food in 2022",
  "deck": "That is 60% of the 1.05 billion tonnes of food wasted worldwide. Food service wasted 290 million tonnes and retail 131 million.",
  "hook": {
    "value": 19,
    "total": 100,
    "text": "tonnes of food that reach shops, restaurants and homes are thrown away.",
    "detail": "That was 1.05 billion tonnes in 2022."
  },
  "hero": {
    "type": "bar-chart",
    "data": [
      { "sector": "Households", "mt": 631 },
      { "sector": "Food service", "mt": 290 },
      { "sector": "Retail", "mt": 131 }
    ],
    "x": "sector",
    "y": "mt",
    "sort": "none",
    "orientation": "horizontal",
    "highlight": "Households",
    "format": "{value} Mt",
    "title": "Households produced 60% of the world's food waste in 2022",
    "subtitle": "Food waste by sector, million tonnes (Mt), 2022",
    "source": "UNEP Food Waste Index Report 2024",
    "note": "Figures are approximate, for illustration"
  },
  "heroText": "Food service produced 290 million tonnes, or 28%. Retail produced 131 million tonnes, or 12%.",
  "sections": [
    {
      "title": "Household food waste by income group",
      "text": "Households in high-income countries waste 81 kg of food per person a year. In upper-middle-income countries the figure is 88 kg. In lower-middle-income countries it is 86 kg.",
      "exhibit": {
        "type": "bar-chart",
        "data": [
          { "group": "High income", "kg": 81 },
          { "group": "Upper-middle", "kg": 88 },
          { "group": "Lower-middle", "kg": 86 }
        ],
        "x": "group",
        "y": "kg",
        "sort": "none",
        "orientation": "horizontal",
        "format": "{value} kg",
        "subtitle": "Household food waste per person per year, by country income group"
      },
      "takeaway": "The three income groups are within 7 kg per person of each other."
    },
    {
      "title": "Lost and wasted food causes 4.4 billion tonnes of emissions a year",
      "text": "Growing, transporting and chilling food uses land, fertiliser and fuel. Food releases methane when it rots. Lost and wasted food causes 8 to 10% of global greenhouse gas emissions.",
      "exhibit": {
        "type": "bar-chart",
        "data": [
          { "emitter": "China", "gt": 13 },
          { "emitter": "United States", "gt": 6 },
          { "emitter": "Wasted food", "gt": 4.4 },
          { "emitter": "India", "gt": 3.9 },
          { "emitter": "European Union", "gt": 3.4 }
        ],
        "x": "emitter",
        "y": "gt",
        "sort": "desc",
        "orientation": "horizontal",
        "highlight": "Wasted food",
        "format": "{value} Gt",
        "subtitle": "Annual greenhouse gas emissions, billion tonnes of CO2 equivalent. Wasted food includes losses before retail"
      },
      "takeaway": "Only China and the United States emit more than lost and wasted food."
    },
    {
      "title": "733 million people faced hunger in 2023",
      "exhibit": {
        "type": "icon-stat",
        "icon": "person",
        "count": 1,
        "total": 11,
        "columns": 11,
        "text": "people in the world faced hunger in 2023."
      }
    }
  ],
  "conclusion": {
    "title": "The UN target is to halve food waste by 2030",
    "text": "Britain and Japan publish household food waste figures. Britain has cut household waste by 18% and Japan by 31%.",
    "points": [
      "Measure household food waste and publish the figure every year.",
      "State on packaging that “best before” refers to quality and “use by” refers to safety.",
      "Plan meals before shopping and freeze food that will not be eaten in time."
    ],
    "action": {
      "label": "Read the UNEP report",
      "href": "https://www.unep.org/resources/publication/food-waste-index-report-2024"
    }
  },
  "sources": [
    {
      "name": "UNEP Food Waste Index Report 2024",
      "url": "https://www.unep.org/resources/publication/food-waste-index-report-2024"
    },
    "FAO, State of Food Security and Nutrition in the World 2024",
    "Emissions figures rounded from national inventories"
  ],
  "note": "Figures are approximate, for illustration",
  "period": "2022 (waste), 2023 (hunger and emissions)",
  "method": "Food waste is measured at retail, food service and household level and includes inedible parts. Losses on farms and in transport are counted separately."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The main finding, as one plain sentence with the number and the period in it. |
| `kicker` | `string` |  | Small label above the title. |
| `deck` | `string` |  | One-sentence standfirst. |
| `byline` | `string` |  | Author line. |
| `date` | `string` |  | Publication date. |
| `hook` | `{ value, total?, text?, figure?, visual?, icon?, detail?, label?, context?, format? } \| Slot` |  | The opening number. With `text` it renders a `proportion-statement` ("19 in every 100 ..."); with `label` a hero `big-number`. A spec or element is rendered as given. |
| `hero` | `Slot` |  | The main exhibit. Its `title` states one fact with its number. Default height 360px. |
| `heroText` | `string` |  | One or two sentences under the hero. Each states one more fact. |
| `sections` | `{ title, text?, exhibit?, takeaway?, id? }[]` |  | Numbered sections. Each has a heading, one exhibit and a `takeaway` sentence with its main number. |
| `screenful` | `boolean` | `false` | Give every section at least the height of the viewport and centre its content, so each fills a screen. |
| `conclusion` | `{ title, text?, points?, action?: { label, href } }` |  | The closing block: a heading, text, a list of actions and an optional link. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `maxWidth` | `number \| string` |  | Widest the piece may get. It is centred in wider containers. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [big-number](https://insightcharts.dev/llms/big-number.md), [proportion-statement](https://insightcharts.dev/llms/proportion-statement.md), [step-marker](https://insightcharts.dev/llms/step-marker.md), [prose](https://insightcharts.dev/llms/prose.md), [callout](https://insightcharts.dev/llms/callout.md), [source-note](https://insightcharts.dev/llms/source-note.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [icon-stat](https://insightcharts.dev/llms/icon-stat.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [segmented-bar](https://insightcharts.dev/llms/segmented-bar.md)
- Used by: no molecule or template yet

### More examples

#### Personal finance, opening with a big number

```tsx
import { BarChart, Explainer, LineChart, SegmentedBar } from "insightcharts";

<Explainer
  kicker="Money basics"
  title="Starting to save at 35 instead of 25 leaves $296,000 less at 65"
  deck="Both savers put in $300 a month at a 6% real return. The saver who starts at 25 has $597,000 at 65. The saver who starts at 35 has $301,000."
  hook={{
    value: 296000,
    format: { style: "currency", currency: "USD", maximumFractionDigits: 0 },
    label: "Difference at 65 between starting at 25 and starting at 35",
    context: "Saving $300 a month until 65 at a 6% real return gives $597k from age 25 and $301k from age 35",
  }}
  hero={<LineChart
    data={[
      { age: "25", saver: "Starts at 25", balance: 0 },
      { age: "30", saver: "Starts at 25", balance: 20931 },
      { age: "35", saver: "Starts at 25", balance: 49164 },
      { age: "35", saver: "Starts at 35", balance: 0 },
      { age: "40", saver: "Starts at 25", balance: 87246 },
      { age: "40", saver: "Starts at 35", balance: 20931 },
      { age: "45", saver: "Starts at 25", balance: 138612 },
      { age: "45", saver: "Starts at 35", balance: 49164 },
      { age: "50", saver: "Starts at 25", balance: 207898 },
      { age: "50", saver: "Starts at 35", balance: 87246 },
      { age: "55", saver: "Starts at 25", balance: 301355 },
      { age: "55", saver: "Starts at 35", balance: 138612 },
      { age: "60", saver: "Starts at 25", balance: 427413 },
      { age: "60", saver: "Starts at 35", balance: 207898 },
      { age: "65", saver: "Starts at 25", balance: 597447 },
      { age: "65", saver: "Starts at 35", balance: 301355 },
    ]}
    x="age"
    y="balance"
    series="saver"
    highlight="Starts at 25"
    format="compact"
    zero
    height={320}
    title="At 50 the saver who started at 25 has $208,000 and the other has $87,000"
    subtitle="Balance by age, $300 a month at a 6% real annual return"
    note="Illustrative calculation"
  />}
  heroText="The saver who starts at 25 deposits $36,000 more. The other $260,000 of the difference is investment growth."
  sections={[
    {
      title: "Deposits are $144,000 of the $597,000",
      text: "The saver who starts at 25 pays in $300 a month for 40 years. The other $453,000 is growth.",
      exhibit: <SegmentedBar
        data={[{ part: "Deposits", usd: 144000 }, { part: "Growth", usd: 453447 }]}
        name="part"
        value="usd"
        format="compact"
        highlight="Growth"
      />,
      takeaway: "Growth is 76% of the final balance.",
    },
    {
      title: "A 1.5% annual fee leaves $402,000 instead of $566,000",
      text: "The index fund charges 0.2% a year. The managed fund charges 1.5%. After 40 years the managed fund's balance is 29% lower.",
      exhibit: <BarChart
        data={[
          { fund: "Index fund, 0.2% a year", balance: 566005 },
          { fund: "Managed fund, 1.5% a year", balance: 402345 },
        ]}
        x="fund"
        y="balance"
        sort="none"
        orientation="horizontal"
        format="compact"
        highlight="Index fund, 0.2% a year"
      />,
    },
  ]}
  conclusion={{
    title: "What to do",
    points: [
      "Set up a monthly standing order this month.",
      "Choose a broad index fund with a fee of about 0.2% a year.",
      "Increase the monthly amount each time your pay rises.",
    ],
  }}
  sources="Author's calculation"
  method="Monthly compounding at a constant real return of 6% a year. Fees are subtracted from the return. Real returns vary from year to year."
  note="Illustrative data. Not financial advice."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/explainer.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/explainer.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Flow poster (`flow-poster`)

> A portrait poster of where something comes from and where it goes, in three stacked bands painted in one colour: the producers as large labelled tiles, the leading producer's output fanning out as ribbons to an aligned column of destinations, and the destinations as bubbles on a scale of how much each depends on that producer.

- Component: `FlowPoster` (import from `insightcharts`)
- Spec type: `"flow-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when one producer leads and the reader should follow its output: ports and the buyers of one port's catch, regions and the users of one region's electricity, terminals and the routes out of the largest. Give `producers` 4 to 10 rows, `flow` 4 to 12 destinations of the leading producer, and `scale` the same destinations with a share (position) and a size. Keep the destination names identical in `flow` and `scale` so `linked` can join them.

### Avoid

Flows through more than one stage or between many sources and many destinations (use `sankey-chart` in a `poster`). A count of people or things (use `count-poster`). Many measures of the same entities (use `matrix-poster`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/flow-poster
```

The file lands at `components/insightcharts/templates/flow-poster.tsx`. `@insightcharts/flow-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { FlowPoster } from "insightcharts";

<FlowPoster
  theme="magenta"
  kicker="Fishing"
  title="Six ports on the Verran Coast landed 412,000 tonnes of fish in 2025"
  subtitle="Landings by port, the buyers of Port Alda's catch, and how much each buyer relies on Port Alda. Thousand tonnes (kt)."
  format="{value} kt"
  producers={{
    data: [
      { port: "Port Alda", kt: 148 },
      { port: "Skerry", kt: 96 },
      { port: "Marrow Bay", kt: 71 },
      { port: "Tolven", kt: 52 },
      { port: "Hask", kt: 28 },
      { port: "Lund", kt: 17 },
    ],
    name: "port",
    value: "kt",
    title: "Port Alda landed 148,000 of the 412,000 tonnes",
  }}
  flow={{
    data: [
      { buyer: "Canneries", kt: 46 },
      { buyer: "Fresh markets", kt: 34 },
      { buyer: "Frozen export", kt: 29 },
      { buyer: "Fishmeal plants", kt: 21 },
      { buyer: "Restaurants", kt: 11 },
      { buyer: "Smokehouses", kt: 7 },
    ],
    name: "buyer",
    value: "kt",
    trunk: "Port Alda",
    title: "Canneries bought 46,000 tonnes of Port Alda's catch",
  }}
  scale={{
    data: [
      { buyer: "Canneries", fromAlda: 56, kt: 82 },
      { buyer: "Fresh markets", fromAlda: 35, kt: 96 },
      { buyer: "Frozen export", fromAlda: 23, kt: 124 },
      { buyer: "Fishmeal plants", fromAlda: 34, kt: 61 },
      { buyer: "Restaurants", fromAlda: 29, kt: 38 },
      { buyer: "Smokehouses", fromAlda: 64, kt: 11 },
    ],
    name: "buyer",
    value: "fromAlda",
    size: "kt",
    sizeFormat: "{value} kt",
    scaleLabel: "From Port Alda",
    title: "Smokehouses bought 64% of their fish from Port Alda",
    subtitle: "Share of each buyer's fish landed at Port Alda (position) and all the fish it bought (area)",
  }}
  sources="Verran Coast Fisheries Board landing returns"
  note="The Verran Coast is an invented place. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "flow-poster",
  "theme": "magenta",
  "kicker": "Fishing",
  "title": "Six ports on the Verran Coast landed 412,000 tonnes of fish in 2025",
  "subtitle": "Landings by port, the buyers of Port Alda's catch, and how much each buyer relies on Port Alda. Thousand tonnes (kt).",
  "format": "{value} kt",
  "producers": {
    "data": [
      { "port": "Port Alda", "kt": 148 },
      { "port": "Skerry", "kt": 96 },
      { "port": "Marrow Bay", "kt": 71 },
      { "port": "Tolven", "kt": 52 },
      { "port": "Hask", "kt": 28 },
      { "port": "Lund", "kt": 17 }
    ],
    "name": "port",
    "value": "kt",
    "title": "Port Alda landed 148,000 of the 412,000 tonnes"
  },
  "flow": {
    "data": [
      { "buyer": "Canneries", "kt": 46 },
      { "buyer": "Fresh markets", "kt": 34 },
      { "buyer": "Frozen export", "kt": 29 },
      { "buyer": "Fishmeal plants", "kt": 21 },
      { "buyer": "Restaurants", "kt": 11 },
      { "buyer": "Smokehouses", "kt": 7 }
    ],
    "name": "buyer",
    "value": "kt",
    "trunk": "Port Alda",
    "title": "Canneries bought 46,000 tonnes of Port Alda's catch"
  },
  "scale": {
    "data": [
      { "buyer": "Canneries", "fromAlda": 56, "kt": 82 },
      { "buyer": "Fresh markets", "fromAlda": 35, "kt": 96 },
      { "buyer": "Frozen export", "fromAlda": 23, "kt": 124 },
      { "buyer": "Fishmeal plants", "fromAlda": 34, "kt": 61 },
      { "buyer": "Restaurants", "fromAlda": 29, "kt": 38 },
      { "buyer": "Smokehouses", "fromAlda": 64, "kt": 11 }
    ],
    "name": "buyer",
    "value": "fromAlda",
    "size": "kt",
    "sizeFormat": "{value} kt",
    "scaleLabel": "From Port Alda",
    "title": "Smokehouses bought 64% of their fish from Port Alda",
    "subtitle": "Share of each buyer's fish landed at Port Alda (position) and all the fish it bought (area)"
  },
  "sources": "Verran Coast Fisheries Board landing returns",
  "note": "The Verran Coast is an invented place. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `producers` (required) | `{ data, name, value, title?, subtitle?, source?, ...treemap props } \| Slot` |  | Top band: the producers as tiles sized by output (`treemap`). The leading one is painted in the accent. |
| `lead` | `string` |  | The producer the flow starts from. Default: the largest row of `producers`. It names the block the ribbons leave. |
| `flow` (required) | `{ data, name, value, trunk?, tagged?, tagLabel?, title?, ...fan-flow props } \| Slot` |  | Middle band: one ribbon per destination, as thick as its value, ending at a column of names, values and shares (`fan-flow`). |
| `scale` | `{ data, name, value, size, scaleLabel?, sizeFormat?, title?, ...bubble-scale props } \| Slot` |  | Bottom band: one bubble per destination, placed by `value` on a 0 to 100 scale and sized by `size` (`bubble-scale`). Set `domain` and `ticks` for a scale that is not a percentage. |
| `format` | `FormatSpec` |  | How to print the quantities of the top and middle bands, e.g. `"{value} kt"`. |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"magenta"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `920` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [treemap](https://insightcharts.dev/llms/treemap.md), [fan-flow](https://insightcharts.dev/llms/fan-flow.md), [bubble-scale](https://insightcharts.dev/llms/bubble-scale.md)
- Used by: no molecule or template yet

### More examples

#### Ocean, electricity from one region, linked

```tsx
import { FlowPoster } from "insightcharts";

<FlowPoster
  theme="ocean"
  linked
  kicker="Energy"
  title="Norrask generated 175 TWh of electricity in 2025"
  subtitle="Generation by region, the users of Fjordland's output, and Fjordland's share of each user's supply. Terawatt-hours (TWh)."
  format="{value} TWh"
  producers={{
    data: [
      { region: "Fjordland", twh: 64 },
      { region: "Highmoor", twh: 41 },
      { region: "Eastmark", twh: 33 },
      { region: "Sundby", twh: 22 },
      { region: "Lowlands", twh: 15 },
    ],
    name: "region",
    value: "twh",
    title: "Fjordland generated 64 of the 175 TWh",
  }}
  flow={{
    data: [
      { user: "Fjordland homes", twh: 22 },
      { user: "Capital region", twh: 14 },
      { user: "Aluminium smelters", twh: 11 },
      { user: "Export to Vesterhav", twh: 8 },
      { user: "Export to Kalmar", twh: 5 },
      { user: "Data centres", twh: 4 },
    ],
    name: "user",
    value: "twh",
    trunk: "Fjordland",
    tagged: ["Export to Vesterhav", "Export to Kalmar"],
    tagLabel: "Leaves the country",
    title: "Fjordland's own homes used 22 of its 64 TWh",
  }}
  scale={{
    data: [
      { user: "Fjordland homes", share: 81, twh: 27 },
      { user: "Capital region", share: 38, twh: 37 },
      { user: "Aluminium smelters", share: 92, twh: 12 },
      { user: "Export to Vesterhav", share: 12, twh: 67 },
      { user: "Export to Kalmar", share: 7, twh: 71 },
      { user: "Data centres", share: 57, twh: 7 },
    ],
    name: "user",
    value: "share",
    size: "twh",
    sizeFormat: "{value} TWh",
    scaleLabel: "From Fjordland",
    title: "Aluminium smelters took 92% of their electricity from Fjordland",
    subtitle: "Fjordland's share of each user's electricity (position) and the user's total demand (area)",
  }}
  sources="Norrask Grid Agency annual balance"
  note="Norrask is an invented country. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Sunrise, containers through one port, with download

```tsx
import { FlowPoster } from "insightcharts";

<FlowPoster
  theme="sunrise"
  download
  kicker="Trade"
  title="The Port of Hallin handled 9.6 million containers in 2025"
  subtitle="Containers by terminal, the routes out of North Quay, and North Quay's share of each destination's containers. Thousand containers."
  format="integer"
  producers={{
    data: [
      { terminal: "North Quay", teu: 3400 },
      { terminal: "Delta", teu: 2300 },
      { terminal: "Old Dock", teu: 1700 },
      { terminal: "Riverside", teu: 1300 },
      { terminal: "Eastgate", teu: 900 },
    ],
    name: "terminal",
    value: "teu",
    title: "North Quay handled 3.4 million of the 9.6 million containers",
  }}
  flow={{
    data: [
      { route: "Mereford by rail", teu: 980 },
      { route: "Castren by rail", teu: 720 },
      { route: "Ulm Lakes by barge", teu: 610 },
      { route: "Hallin city by road", teu: 520 },
      { route: "Dunmore by road", teu: 340 },
      { route: "Skaw by feeder ship", teu: 230 },
    ],
    name: "route",
    value: "teu",
    trunk: "North Quay",
    title: "980,000 containers left North Quay by rail for Mereford",
  }}
  scale={{
    data: [
      { route: "Mereford by rail", share: 70, teu: 1400 },
      { route: "Castren by rail", share: 45, teu: 1600 },
      { route: "Ulm Lakes by barge", share: 80, teu: 760 },
      { route: "Hallin city by road", share: 25, teu: 2080 },
      { route: "Dunmore by road", share: 30, teu: 1130 },
      { route: "Skaw by feeder ship", share: 10, teu: 2300 },
    ],
    name: "route",
    value: "share",
    size: "teu",
    sizeFormat: "integer",
    scaleLabel: "Via North Quay",
    title: "Ulm Lakes received 80% of its containers through North Quay",
    subtitle: "North Quay's share of each destination's containers (position) and all the containers it received, thousands (area)",
  }}
  sources="Hallin Port Authority throughput statistics"
  note="The Port of Hallin is an invented port. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/flow-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/flow-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Matrix poster (`matrix-poster`)

> One wide landscape graphic that compares 4 to 12 entities on five to seven measures: two measures as S-curves between parallel scales on the left, joined to a table on the right in which every other number is drawn as dots, squares, icons, a ring, a circle or a bar. Both halves share one row order and one colour per entity.

- Component: `MatrixPoster` (import from `insightcharts`)
- Spec type: `"matrix-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for profiles of a handful of comparable things with measures in different units: cities, species, products, stations, teams. Pass one row per entity with every measure in it. Put the two measures whose relationship matters in `curve` and the rest in `columns`, choosing a counted glyph (`dots`, `blocks`, `icons`) for small whole numbers, `ring` for shares, `bar` or `circle` for magnitudes. Leave `highlight` out to give every entity its own colour, derived from the theme when its palette is smaller than the number of entities; set it to draw one or two entities in colour and the rest in grey.

### Avoid

One measure across entities (use `pill-rank` or `bar-chart`). More than 12 entities (use `data-table` or `heatmap`). A subject with a total and its parts (use `ranking-poster` or `flow-poster`). A phone-first piece: the table stacks into cards under 600px and the poster becomes long.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/matrix-poster
```

The file lands at `components/insightcharts/templates/matrix-poster.tsx`. `@insightcharts/matrix-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { MatrixPoster } from "insightcharts";

<MatrixPoster
  theme="paper"
  kicker="Cities"
  title="A one-bedroom flat in Avenmouth rented for €1,640 a month in 2025"
  subtitle="Eight cities of Norland compared on rent, pay and five measures of daily life, 2025."
  rows={[
    {
      city: "Avenmouth",
      rent: 1640,
      pay: 3900,
      transit: 38,
      parks: 14,
      lanes: 212,
      cafes: 23,
      sun: 148,
    },
    {
      city: "Brackley Bay",
      rent: 1480,
      pay: 3300,
      transit: 22,
      parks: 9,
      lanes: 96,
      cafes: 17,
      sun: 201,
    },
    {
      city: "Castren",
      rent: 1310,
      pay: 3600,
      transit: 41,
      parks: 17,
      lanes: 184,
      cafes: 19,
      sun: 132,
    },
    {
      city: "Dunmore",
      rent: 1150,
      pay: 2900,
      transit: 27,
      parks: 11,
      lanes: 120,
      cafes: 12,
      sun: 165,
    },
    {
      city: "Eastwick",
      rent: 980,
      pay: 3100,
      transit: 33,
      parks: 21,
      lanes: 240,
      cafes: 15,
      sun: 121,
    },
    {
      city: "Fenhallow",
      rent: 860,
      pay: 2500,
      transit: 18,
      parks: 8,
      lanes: 54,
      cafes: 9,
      sun: 176,
    },
    {
      city: "Greyport",
      rent: 740,
      pay: 2700,
      transit: 24,
      parks: 12,
      lanes: 88,
      cafes: 11,
      sun: 190,
    },
    { city: "Hallin", rent: 610, pay: 2200, transit: 12, parks: 6, lanes: 31, cafes: 7, sun: 210 },
  ]}
  name="city"
  nameLabel="City"
  curve={{
    left: "rent",
    right: "pay",
    leftLabel: "Rent, € a month",
    rightLabel: "Median pay, € a month",
    format: "integer",
    title: "Median pay in Avenmouth was €3,900 a month",
  }}
  columns={[
    { field: "transit", label: "Trips by public transport", glyph: "ring", format: "{value}%" },
    { field: "parks", label: "Parks per 100,000 people", glyph: "dots" },
    { field: "lanes", label: "Cycle lanes, km", glyph: "bar" },
    { field: "cafes", label: "Cafés per 10,000 people", glyph: "blocks" },
    { field: "sun", label: "Sunny days a year", glyph: "circle" },
  ]}
  table={{ title: "Eastwick had 240 km of cycle lanes" }}
  sources="Norland Statistics Office, city indicators 2025"
  note="Norland and its cities are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "matrix-poster",
  "theme": "paper",
  "kicker": "Cities",
  "title": "A one-bedroom flat in Avenmouth rented for €1,640 a month in 2025",
  "subtitle": "Eight cities of Norland compared on rent, pay and five measures of daily life, 2025.",
  "rows": [
    {
      "city": "Avenmouth",
      "rent": 1640,
      "pay": 3900,
      "transit": 38,
      "parks": 14,
      "lanes": 212,
      "cafes": 23,
      "sun": 148
    },
    {
      "city": "Brackley Bay",
      "rent": 1480,
      "pay": 3300,
      "transit": 22,
      "parks": 9,
      "lanes": 96,
      "cafes": 17,
      "sun": 201
    },
    {
      "city": "Castren",
      "rent": 1310,
      "pay": 3600,
      "transit": 41,
      "parks": 17,
      "lanes": 184,
      "cafes": 19,
      "sun": 132
    },
    {
      "city": "Dunmore",
      "rent": 1150,
      "pay": 2900,
      "transit": 27,
      "parks": 11,
      "lanes": 120,
      "cafes": 12,
      "sun": 165
    },
    {
      "city": "Eastwick",
      "rent": 980,
      "pay": 3100,
      "transit": 33,
      "parks": 21,
      "lanes": 240,
      "cafes": 15,
      "sun": 121
    },
    {
      "city": "Fenhallow",
      "rent": 860,
      "pay": 2500,
      "transit": 18,
      "parks": 8,
      "lanes": 54,
      "cafes": 9,
      "sun": 176
    },
    {
      "city": "Greyport",
      "rent": 740,
      "pay": 2700,
      "transit": 24,
      "parks": 12,
      "lanes": 88,
      "cafes": 11,
      "sun": 190
    },
    {
      "city": "Hallin",
      "rent": 610,
      "pay": 2200,
      "transit": 12,
      "parks": 6,
      "lanes": 31,
      "cafes": 7,
      "sun": 210
    }
  ],
  "name": "city",
  "nameLabel": "City",
  "curve": {
    "left": "rent",
    "right": "pay",
    "leftLabel": "Rent, € a month",
    "rightLabel": "Median pay, € a month",
    "format": "integer",
    "title": "Median pay in Avenmouth was €3,900 a month"
  },
  "columns": [
    {
      "field": "transit",
      "label": "Trips by public transport",
      "glyph": "ring",
      "format": "{value}%"
    },
    { "field": "parks", "label": "Parks per 100,000 people", "glyph": "dots" },
    { "field": "lanes", "label": "Cycle lanes, km", "glyph": "bar" },
    { "field": "cafes", "label": "Cafés per 10,000 people", "glyph": "blocks" },
    { "field": "sun", "label": "Sunny days a year", "glyph": "circle" }
  ],
  "table": { "title": "Eastwick had 240 km of cycle lanes" },
  "sources": "Norland Statistics Office, city indicators 2025",
  "note": "Norland and its cities are invented. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `rows` (required) | `Row[]` |  | One object per entity, holding the name and every measure. |
| `name` | `string` |  | Field holding the entity name. Default: the first key of the first row. |
| `nameLabel` | `string` |  | Heading of the table's name column. |
| `curve` (required) | `{ left, right, leftLabel?, rightLabel?, leftFormat?, rightFormat?, leftTop?, rightTop?, title?, subtitle?, source?, ...curve-rank props }` |  | Left graphic: the two measures joined by one S-curve per entity (`curve-rank`). The poster's rows are ordered by `left`, largest first. |
| `columns` (required) | `{ field, label?, glyph?, unit?, format?, max?, icon? }[]` |  | Right graphic: the glyph columns of the table, in order (`glyph-table`). Three to five read well beside the curves. |
| `table` | `{ title?, subtitle?, source?, note? }` |  | Short heading and source line over and under the table. |
| `order` | `string[]` |  | Entity names in display order, for both graphics. Default: largest first on the curve's left measure. |
| `highlight` | `string \| string[]` |  | Entities drawn in colour while every other one turns grey. Without it each entity has its own colour in both graphics. |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"paper"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `1400` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [curve-rank](https://insightcharts.dev/llms/curve-rank.md), [glyph-table](https://insightcharts.dev/llms/glyph-table.md)
- Used by: no molecule or template yet

### More examples

#### Noir, eight seabirds, linked

```tsx
import { MatrixPoster } from "insightcharts";

<MatrixPoster
  theme="noir"
  linked
  kicker="Wildlife"
  title="21,400 pairs of guillemots bred on the Skerry Isles in 2025"
  subtitle="Eight seabird species compared on wingspan, breeding pairs and four other measures."
  rows={[
    { bird: "Gannet", wingspan: 180, pairs: 5200, eggs: 1, dive: 22, years: 17, mass: 3000 },
    { bird: "Fulmar", wingspan: 107, pairs: 8900, eggs: 1, dive: 3, years: 30, mass: 800 },
    { bird: "Kittiwake", wingspan: 105, pairs: 14600, eggs: 2, dive: 1, years: 12, mass: 400 },
    { bird: "Shag", wingspan: 100, pairs: 1900, eggs: 3, dive: 45, years: 12, mass: 1900 },
    { bird: "Arctic tern", wingspan: 80, pairs: 3100, eggs: 2, dive: 1, years: 13, mass: 110 },
    { bird: "Guillemot", wingspan: 67, pairs: 21400, eggs: 1, dive: 60, years: 23, mass: 950 },
    { bird: "Razorbill", wingspan: 65, pairs: 6700, eggs: 1, dive: 35, years: 13, mass: 620 },
    { bird: "Puffin", wingspan: 55, pairs: 11800, eggs: 1, dive: 40, years: 18, mass: 400 },
  ]}
  name="bird"
  nameLabel="Species"
  curve={{
    left: "wingspan",
    right: "pairs",
    leftLabel: "Wingspan, cm",
    rightLabel: "Breeding pairs",
    format: "integer",
    title: "The gannet's wingspan is 180 cm",
  }}
  columns={[
    { field: "eggs", label: "Eggs in a clutch", glyph: "dots" },
    { field: "dive", label: "Deepest dive, m", glyph: "bar", format: "{value} m" },
    { field: "years", label: "Typical lifespan, years", glyph: "blocks" },
    { field: "mass", label: "Body mass, g", glyph: "circle", format: "integer" },
  ]}
  table={{ title: "Guillemots dive to 60 metres" }}
  sources="Skerry Isles seabird census 2025"
  note="The Skerry Isles and the colony counts are invented. Species measurements are rounded typical values."
  credit="InsightCharts"
/>
```

#### Blueprint, ten weather stations, one highlighted, with download

```tsx
import { MatrixPoster } from "insightcharts";

<MatrixPoster
  theme="blueprint"
  download
  kicker="Weather"
  title="Skarvik recorded 2,240 mm of rain in 2025"
  subtitle="Ten weather stations in Norland compared on rainfall, altitude and five other measures, 2025."
  rows={[
    {
      station: "Skarvik",
      altitude: 12,
      rain: 2240,
      wet: 231,
      july: 13,
      snow: 18,
      wind: 31,
      sun: 1090,
    },
    {
      station: "Holm Pass",
      altitude: 940,
      rain: 1860,
      wet: 204,
      july: 9,
      snow: 142,
      wind: 27,
      sun: 1180,
    },
    {
      station: "Tarn Head",
      altitude: 610,
      rain: 1610,
      wet: 196,
      july: 11,
      snow: 96,
      wind: 22,
      sun: 1240,
    },
    {
      station: "Aldern",
      altitude: 180,
      rain: 1240,
      wet: 172,
      july: 15,
      snow: 31,
      wind: 16,
      sun: 1410,
    },
    {
      station: "Norvik",
      altitude: 35,
      rain: 1090,
      wet: 168,
      july: 14,
      snow: 24,
      wind: 24,
      sun: 1380,
    },
    {
      station: "Castren",
      altitude: 95,
      rain: 880,
      wet: 151,
      july: 17,
      snow: 19,
      wind: 14,
      sun: 1620,
    },
    {
      station: "Mereford",
      altitude: 240,
      rain: 760,
      wet: 139,
      july: 18,
      snow: 27,
      wind: 13,
      sun: 1710,
    },
    { station: "Sundby", altitude: 8, rain: 690, wet: 128, july: 17, snow: 11, wind: 21, sun: 1840 },
    {
      station: "Dunmore",
      altitude: 310,
      rain: 610,
      wet: 117,
      july: 19,
      snow: 38,
      wind: 12,
      sun: 1790,
    },
    {
      station: "Eastmark",
      altitude: 420,
      rain: 480,
      wet: 96,
      july: 20,
      snow: 44,
      wind: 15,
      sun: 1930,
    },
  ]}
  name="station"
  nameLabel="Station"
  highlight="Skarvik"
  curve={{
    left: "rain",
    right: "altitude",
    leftLabel: "Rain in 2025, mm",
    rightLabel: "Altitude, m",
    format: "integer",
    title: "Skarvik stands 12 metres above the sea",
  }}
  columns={[
    { field: "wet", label: "Days with rain", glyph: "dots", unit: 10 },
    { field: "july", label: "Mean July temperature", glyph: "bar", format: "{value}°C" },
    { field: "snow", label: "Days with snow", glyph: "bar" },
    { field: "wind", label: "Mean wind, km/h", glyph: "circle" },
    { field: "sun", label: "Hours of sunshine", glyph: "bar", format: "integer" },
  ]}
  table={{ title: "Rain fell at Skarvik on 231 days" }}
  sources="Norland Meteorological Institute station records 2025"
  note="Norland and its weather stations are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/matrix-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/matrix-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Network poster (`network-poster`)

> A poster of who is connected to whom: a full-width arc diagram with one arc per connection, as thick as its value (`arc-diagram`), a strip of two to four large figures, and a bottom row where the same entities return as circles joined by lines (`bubble-network`) and as a ranking of centred pills (`pill-rank`).

- Component: `NetworkPoster` (import from `insightcharts`)
- Spec type: `"network-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when the connections between 5 to about 20 named things are the subject: ferry crossings between harbours, joint papers between institutes, freight between rail yards. Give `hero` one row per connection and the `order` the entities sit in, `map` the entities with a size and optional hand-placed `x` and `y`, and `rank` one measure of each entity. With `linked`, a click on an entity in any of the three highlights it in the other two.

### Avoid

A flow from sources to destinations in one direction (use `flow-poster` or `sankey-chart`). More than about 20 entities or 40 connections, because the arcs cover each other. Entities with no meaningful order and few links (use `bubble-network` in a `poster`). Parts of one subject (use `radial-poster`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/network-poster
```

The file lands at `components/insightcharts/templates/network-poster.tsx`. `@insightcharts/network-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { NetworkPoster } from "insightcharts";

<NetworkPoster
  theme="dusk"
  linked
  kicker="Ferries"
  title="Skerry Isles ferries carried 1.66 million passengers on 12 routes in 2025"
  subtitle="Passengers carried between pairs of harbours, thousands, both directions, 2025."
  hero={{
    data: [
      { a: "Port Aven", b: "Brae", k: 412 },
      { a: "Port Aven", b: "Storholm", k: 268 },
      { a: "Port Aven", b: "Little Skerry", k: 96 },
      { a: "Brae", b: "Storholm", k: 187 },
      { a: "Brae", b: "Tarn Head", k: 74 },
      { a: "Storholm", b: "Tarn Head", k: 153 },
      { a: "Storholm", b: "Ness", k: 121 },
      { a: "Tarn Head", b: "Ness", k: 88 },
      { a: "Ness", b: "Outer Holm", k: 43 },
      { a: "Little Skerry", b: "Brae", k: 52 },
      { a: "Port Aven", b: "Ness", k: 139 },
      { a: "Storholm", b: "Outer Holm", k: 31 },
    ],
    from: "a",
    to: "b",
    value: "k",
    order: ["Port Aven", "Little Skerry", "Brae", "Storholm", "Tarn Head", "Ness", "Outer Holm"],
    colorBy: "series",
    format: "{value}k",
    title: "412,000 passengers crossed between Port Aven and Brae",
  }}
  figures={[
    { value: "412k", label: "passengers on the busiest route", context: "Port Aven to Brae" },
    { value: "31k", label: "passengers on the quietest route", context: "Storholm to Outer Holm" },
    { value: "4", label: "of the 12 routes call at Port Aven" },
  ]}
  map={{
    data: [
      { harbour: "Port Aven", k: 915, x: 12, y: 62 },
      { harbour: "Little Skerry", k: 148, x: 22, y: 18 },
      { harbour: "Brae", k: 725, x: 38, y: 40 },
      { harbour: "Storholm", k: 760, x: 56, y: 80 },
      { harbour: "Tarn Head", k: 315, x: 66, y: 22 },
      { harbour: "Ness", k: 391, x: 84, y: 46 },
      { harbour: "Outer Holm", k: 74, x: 93, y: 82 },
    ],
    name: "harbour",
    value: "k",
    x: "x",
    y: "y",
    links: [
      { from: "Port Aven", to: "Brae" },
      { from: "Port Aven", to: "Storholm" },
      { from: "Port Aven", to: "Little Skerry" },
      { from: "Brae", to: "Storholm" },
      { from: "Brae", to: "Tarn Head" },
      { from: "Storholm", to: "Tarn Head" },
      { from: "Storholm", to: "Ness" },
      { from: "Tarn Head", to: "Ness" },
      { from: "Ness", to: "Outer Holm" },
      { from: "Little Skerry", to: "Brae" },
      { from: "Port Aven", to: "Ness" },
      { from: "Storholm", to: "Outer Holm" },
    ],
    format: "{value}k",
    highlight: "Port Aven",
    tag: "Busiest harbour",
    title: "915,000 passengers used Port Aven",
    subtitle: "Passengers through each harbour, thousands. Positions are approximate.",
  }}
  rank={{
    data: [
      { harbour: "Port Aven", sailings: 46 },
      { harbour: "Storholm", sailings: 38 },
      { harbour: "Brae", sailings: 33 },
      { harbour: "Ness", sailings: 21 },
      { harbour: "Tarn Head", sailings: 16 },
      { harbour: "Little Skerry", sailings: 8 },
      { harbour: "Outer Holm", sailings: 4 },
    ],
    name: "harbour",
    value: "sailings",
    title: "Port Aven had 46 sailings a day",
    subtitle: "Scheduled departures per day, summer 2025.",
  }}
  sources="Skerry Isles Ferries, annual traffic return 2025"
  note="The Skerry Isles are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "network-poster",
  "theme": "dusk",
  "linked": true,
  "kicker": "Ferries",
  "title": "Skerry Isles ferries carried 1.66 million passengers on 12 routes in 2025",
  "subtitle": "Passengers carried between pairs of harbours, thousands, both directions, 2025.",
  "hero": {
    "data": [
      { "a": "Port Aven", "b": "Brae", "k": 412 },
      { "a": "Port Aven", "b": "Storholm", "k": 268 },
      { "a": "Port Aven", "b": "Little Skerry", "k": 96 },
      { "a": "Brae", "b": "Storholm", "k": 187 },
      { "a": "Brae", "b": "Tarn Head", "k": 74 },
      { "a": "Storholm", "b": "Tarn Head", "k": 153 },
      { "a": "Storholm", "b": "Ness", "k": 121 },
      { "a": "Tarn Head", "b": "Ness", "k": 88 },
      { "a": "Ness", "b": "Outer Holm", "k": 43 },
      { "a": "Little Skerry", "b": "Brae", "k": 52 },
      { "a": "Port Aven", "b": "Ness", "k": 139 },
      { "a": "Storholm", "b": "Outer Holm", "k": 31 }
    ],
    "from": "a",
    "to": "b",
    "value": "k",
    "order": ["Port Aven", "Little Skerry", "Brae", "Storholm", "Tarn Head", "Ness", "Outer Holm"],
    "colorBy": "series",
    "format": "{value}k",
    "title": "412,000 passengers crossed between Port Aven and Brae"
  },
  "figures": [
    { "value": "412k", "label": "passengers on the busiest route", "context": "Port Aven to Brae" },
    {
      "value": "31k",
      "label": "passengers on the quietest route",
      "context": "Storholm to Outer Holm"
    },
    { "value": "4", "label": "of the 12 routes call at Port Aven" }
  ],
  "map": {
    "data": [
      { "harbour": "Port Aven", "k": 915, "x": 12, "y": 62 },
      { "harbour": "Little Skerry", "k": 148, "x": 22, "y": 18 },
      { "harbour": "Brae", "k": 725, "x": 38, "y": 40 },
      { "harbour": "Storholm", "k": 760, "x": 56, "y": 80 },
      { "harbour": "Tarn Head", "k": 315, "x": 66, "y": 22 },
      { "harbour": "Ness", "k": 391, "x": 84, "y": 46 },
      { "harbour": "Outer Holm", "k": 74, "x": 93, "y": 82 }
    ],
    "name": "harbour",
    "value": "k",
    "x": "x",
    "y": "y",
    "links": [
      { "from": "Port Aven", "to": "Brae" },
      { "from": "Port Aven", "to": "Storholm" },
      { "from": "Port Aven", "to": "Little Skerry" },
      { "from": "Brae", "to": "Storholm" },
      { "from": "Brae", "to": "Tarn Head" },
      { "from": "Storholm", "to": "Tarn Head" },
      { "from": "Storholm", "to": "Ness" },
      { "from": "Tarn Head", "to": "Ness" },
      { "from": "Ness", "to": "Outer Holm" },
      { "from": "Little Skerry", "to": "Brae" },
      { "from": "Port Aven", "to": "Ness" },
      { "from": "Storholm", "to": "Outer Holm" }
    ],
    "format": "{value}k",
    "highlight": "Port Aven",
    "tag": "Busiest harbour",
    "title": "915,000 passengers used Port Aven",
    "subtitle": "Passengers through each harbour, thousands. Positions are approximate."
  },
  "rank": {
    "data": [
      { "harbour": "Port Aven", "sailings": 46 },
      { "harbour": "Storholm", "sailings": 38 },
      { "harbour": "Brae", "sailings": 33 },
      { "harbour": "Ness", "sailings": 21 },
      { "harbour": "Tarn Head", "sailings": 16 },
      { "harbour": "Little Skerry", "sailings": 8 },
      { "harbour": "Outer Holm", "sailings": 4 }
    ],
    "name": "harbour",
    "value": "sailings",
    "title": "Port Aven had 46 sailings a day",
    "subtitle": "Scheduled departures per day, summer 2025."
  },
  "sources": "Skerry Isles Ferries, annual traffic return 2025",
  "note": "The Skerry Isles are invented. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `hero` (required) | `{ data, from, to, value?, order?, colorBy?, arcLabels?, orientation?, format?, highlight?, title?, ... } \| Slot` |  | The hero: one arc per pair of connected entities, drawn by `arc-diagram`. Rows joining the same pair are summed. A full spec or element replaces it. |
| `figures` | `{ value: string; label: string; context?: string; icon?: string; tag?: string }[]` |  | Two to four large figures in a strip under the hero. |
| `map` | `{ data, name, value, links?, x?, y?, layout?, tag?, highlight?, format?, title?, ... } \| Slot` |  | Bottom left: the entities as circles sized by `value` and joined by `links: { from, to, value? }[]` (`bubble-network`). `x` and `y` (0 to 100) place the circles by hand. |
| `rank` | `{ data, name, value, highlight?, compare?, format?, title?, ... } \| Slot` |  | Bottom right: the entities ranked by one measure as centred pills (`pill-rank`). With only one of `map` and `rank`, that one takes the full width. |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"dusk"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `1100` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [arc-diagram](https://insightcharts.dev/llms/arc-diagram.md), [bubble-network](https://insightcharts.dev/llms/bubble-network.md), [pill-rank](https://insightcharts.dev/llms/pill-rank.md)
- Used by: no molecule or template yet

### More examples

#### Noir, joint papers, a hub layout, with download

```tsx
import { NetworkPoster } from "insightcharts";

<NetworkPoster
  theme="noir"
  download
  kicker="Research"
  title="Six Norland institutes published 369 joint papers in 2025"
  subtitle="Papers with authors at two of the six institutes, by pair, 2025."
  hero={{
    data: [
      { a: "Marlow", b: "Halden", papers: 84 },
      { a: "Marlow", b: "Orrin", papers: 61 },
      { a: "Marlow", b: "Carrow", papers: 37 },
      { a: "Halden", b: "Orrin", papers: 52 },
      { a: "Halden", b: "Kestrel", papers: 29 },
      { a: "Orrin", b: "Carrow", papers: 44 },
      { a: "Orrin", b: "Aldern", papers: 18 },
      { a: "Carrow", b: "Kestrel", papers: 23 },
      { a: "Kestrel", b: "Aldern", papers: 12 },
      { a: "Marlow", b: "Aldern", papers: 9 },
    ],
    from: "a",
    to: "b",
    value: "papers",
    order: ["Marlow", "Halden", "Orrin", "Carrow", "Kestrel", "Aldern"],
    colorBy: "none",
    highlight: "Marlow",
    title: "Marlow and Halden shared 84 papers",
  }}
  figures={[
    { value: "191", label: "of the 369 papers had a Marlow author" },
    { value: "84", label: "papers were shared by Marlow and Halden" },
    { value: "39", label: "papers had an Aldern author" },
  ]}
  map={{
    data: [
      { institute: "Marlow", staff: 640 },
      { institute: "Halden", staff: 510 },
      { institute: "Orrin", staff: 470 },
      { institute: "Carrow", staff: 290 },
      { institute: "Kestrel", staff: 180 },
      { institute: "Aldern", staff: 95 },
    ],
    name: "institute",
    value: "staff",
    layout: "hub",
    links: [
      { from: "Marlow", to: "Halden", value: 84 },
      { from: "Marlow", to: "Orrin", value: 61 },
      { from: "Marlow", to: "Carrow", value: 37 },
      { from: "Halden", to: "Orrin", value: 52 },
      { from: "Halden", to: "Kestrel", value: 29 },
      { from: "Orrin", to: "Carrow", value: 44 },
      { from: "Orrin", to: "Aldern", value: 18 },
      { from: "Carrow", to: "Kestrel", value: 23 },
      { from: "Kestrel", to: "Aldern", value: 12 },
      { from: "Marlow", to: "Aldern", value: 9 },
    ],
    highlight: "Marlow",
    tag: "640 researchers",
    linkLabels: false,
    title: "Marlow employed 640 researchers",
    subtitle: "Research staff at each institute. Line width is the number of joint papers.",
  }}
  rank={{
    data: [
      { institute: "Marlow", staff: 640 },
      { institute: "Halden", staff: 510 },
      { institute: "Orrin", staff: 470 },
      { institute: "Carrow", staff: 290 },
      { institute: "Kestrel", staff: 180 },
      { institute: "Aldern", staff: 95 },
    ],
    name: "institute",
    value: "staff",
    highlight: "Marlow",
    title: "Aldern employed 95 researchers",
  }}
  sources="Norland Research Council, publication register 2025"
  note="The institutes are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Forest, five rail yards, arcs and figures only

```tsx
import { NetworkPoster } from "insightcharts";

<NetworkPoster
  theme="forest"
  kicker="Rail freight"
  title="Halden's five rail yards exchanged 1,670 wagons a week in 2025"
  subtitle="Wagons moved between pairs of yards per week, both directions, average for 2025."
  hero={{
    data: [
      { a: "Northgate", b: "Mill Lane", wagons: 310 },
      { a: "Northgate", b: "Quarry Junction", wagons: 190 },
      { a: "Mill Lane", b: "Quarry Junction", wagons: 240 },
      { a: "Mill Lane", b: "Harbour East", wagons: 420 },
      { a: "Quarry Junction", b: "Harbour East", wagons: 160 },
      { a: "Harbour East", b: "Southfield", wagons: 280 },
      { a: "Northgate", b: "Southfield", wagons: 70 },
    ],
    from: "a",
    to: "b",
    value: "wagons",
    order: ["Northgate", "Mill Lane", "Quarry Junction", "Harbour East", "Southfield"],
    colorBy: "series",
    title: "Mill Lane and Harbour East exchanged 420 wagons a week",
  }}
  figures={[
    { value: "420", label: "wagons a week on the busiest pair" },
    { value: "70", label: "wagons a week between Northgate and Southfield" },
  ]}
  sources="Halden Rail Freight, yard movements 2025"
  note="The Halden yards are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/network-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/network-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Profile poster (`profile-poster`)

> A poster that describes one subject from four sides: the subject as one large silhouette filled to a share (`shape-fill`), two to four large figures, its place among other things on one scale (`scale-ladder`), and a table that sets it beside its peers with every number drawn as a small form (`glyph-table`).

- Component: `ProfilePoster` (import from `insightcharts`)
- Spec type: `"profile-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for a fact sheet about one named thing: a vehicle, a reservoir, a building, a machine, a species. Give `portrait` one row with the share that defines the subject and the `icon` that stands for it, `figures` the numbers a reader should take away, `scale` the subject among 4 to 10 reference points, and `table` the subject beside 2 to 6 peers. Highlight the subject in `scale` and `table`. On a sheet at least 960px wide the silhouette, the figures and the scale stand in three columns.

### Avoid

Several subjects of equal weight (use `glyph-table` in a `poster`, or `ranking-poster`). A subject whose parts are the point (use `radial-poster`). A subject with no defining share: leave `portrait` to a full spec such as `stat-circles`, or use `scale-poster` when the scale is the whole subject. Change over time (use `timeline-poster`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/profile-poster
```

The file lands at `components/insightcharts/templates/profile-poster.tsx`. `@insightcharts/profile-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ProfilePoster } from "insightcharts";

<ProfilePoster
  theme="blueprint"
  kicker="Public transport"
  title="The Line 9 electric bus ended a working day with 34% of its charge"
  subtitle="One 12-metre battery bus on Marlow's Line 9, average of 60 working days in 2025."
  portrait={{
    data: [{ state: "Charge left at 23:00", charge: 34 }],
    name: "state",
    value: "charge",
    icon: "bus",
    title: "Charge left at the end of the day",
  }}
  figures={[
    { value: "204 km", label: "driven on a working day" },
    { value: "310 km", label: "of range on a full charge" },
    { value: "4 h", label: "to recharge overnight at the depot" },
  ]}
  scale={{
    data: [
      { vehicle: "Electric scooter", km: 35, icon: "bolt" },
      { vehicle: "Electric bike", km: 70, icon: "bike" },
      { vehicle: "Delivery van", km: 210, icon: "truck" },
      { vehicle: "Line 9 bus", km: 310, icon: "bus" },
      { vehicle: "Family car", km: 420, icon: "car" },
      { vehicle: "Long-haul truck", km: 520, icon: "truck" },
    ],
    name: "vehicle",
    value: "km",
    iconField: "icon",
    min: 0,
    max: 600,
    format: "{value} km",
    scaleLabel: "Range, km",
    highlight: "Line 9 bus",
    title: "Range of six electric vehicles",
  }}
  table={{
    rows: [
      { vehicle: "Line 9 bus", seats: 41, cost: 0.21, co2: 14, noise: 62 },
      { vehicle: "Diesel bus", seats: 43, cost: 0.58, co2: 71, noise: 78 },
      { vehicle: "Tram", seats: 64, cost: 0.17, co2: 9, noise: 70 },
    ],
    name: "vehicle",
    nameLabel: "Vehicle",
    highlight: "Line 9 bus",
    title: "The Line 9 bus emitted 14 g of CO2 per passenger-kilometre",
    columns: [
      { field: "seats", label: "Seats", glyph: "icons", icon: "person", unit: 5 },
      { field: "cost", label: "Energy cost per km", glyph: "bar", format: "€{value}", max: 0.6 },
      { field: "co2", label: "CO2 per passenger-km", glyph: "circle", format: "{value} g" },
      { field: "noise", label: "Noise at 10 m", glyph: "bar", format: "{value} dB", max: 80 },
    ],
  }}
  sources="Marlow Transit depot telemetry, 2025"
  note="Marlow Transit and the Line 9 bus are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "profile-poster",
  "theme": "blueprint",
  "kicker": "Public transport",
  "title": "The Line 9 electric bus ended a working day with 34% of its charge",
  "subtitle": "One 12-metre battery bus on Marlow's Line 9, average of 60 working days in 2025.",
  "portrait": {
    "data": [{ "state": "Charge left at 23:00", "charge": 34 }],
    "name": "state",
    "value": "charge",
    "icon": "bus",
    "title": "Charge left at the end of the day"
  },
  "figures": [
    { "value": "204 km", "label": "driven on a working day" },
    { "value": "310 km", "label": "of range on a full charge" },
    { "value": "4 h", "label": "to recharge overnight at the depot" }
  ],
  "scale": {
    "data": [
      { "vehicle": "Electric scooter", "km": 35, "icon": "bolt" },
      { "vehicle": "Electric bike", "km": 70, "icon": "bike" },
      { "vehicle": "Delivery van", "km": 210, "icon": "truck" },
      { "vehicle": "Line 9 bus", "km": 310, "icon": "bus" },
      { "vehicle": "Family car", "km": 420, "icon": "car" },
      { "vehicle": "Long-haul truck", "km": 520, "icon": "truck" }
    ],
    "name": "vehicle",
    "value": "km",
    "iconField": "icon",
    "min": 0,
    "max": 600,
    "format": "{value} km",
    "scaleLabel": "Range, km",
    "highlight": "Line 9 bus",
    "title": "Range of six electric vehicles"
  },
  "table": {
    "rows": [
      { "vehicle": "Line 9 bus", "seats": 41, "cost": 0.21, "co2": 14, "noise": 62 },
      { "vehicle": "Diesel bus", "seats": 43, "cost": 0.58, "co2": 71, "noise": 78 },
      { "vehicle": "Tram", "seats": 64, "cost": 0.17, "co2": 9, "noise": 70 }
    ],
    "name": "vehicle",
    "nameLabel": "Vehicle",
    "highlight": "Line 9 bus",
    "title": "The Line 9 bus emitted 14 g of CO2 per passenger-kilometre",
    "columns": [
      { "field": "seats", "label": "Seats", "glyph": "icons", "icon": "person", "unit": 5 },
      {
        "field": "cost",
        "label": "Energy cost per km",
        "glyph": "bar",
        "format": "€{value}",
        "max": 0.6
      },
      { "field": "co2", "label": "CO2 per passenger-km", "glyph": "circle", "format": "{value} g" },
      {
        "field": "noise",
        "label": "Noise at 10 m",
        "glyph": "bar",
        "format": "{value} dB",
        "max": 80
      }
    ]
  },
  "sources": "Marlow Transit depot telemetry, 2025",
  "note": "Marlow Transit and the Line 9 bus are invented. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `portrait` (required) | `{ data, name, value, icon, max?, format?, title?, ... } \| Slot` |  | The portrait: one silhouette filled from the bottom to the share in its row, with the number beside it, drawn by `shape-fill`. `format` defaults to `"{value}%"`. A full spec or element replaces it. |
| `figures` | `{ value: string; label: string; context?: string; icon?: string; tag?: string }[]` |  | Two to four large figures about the subject. In the three-column layout they stand between the silhouette and the scale; otherwise they run in a strip. |
| `scale` | `{ data, name, value, iconField?, direction?, scale?, min?, max?, zones?, scaleLabel?, highlight?, format?, title?, ... } \| Slot` |  | The subject among 4 to 10 other things on one scale (`scale-ladder`). It is drawn as tall as the silhouette. |
| `table` | `{ rows, name, columns, nameLabel?, highlight?, order?, title?, ... } \| Slot` |  | The subject beside its peers, one row each, with a glyph per measure (`glyph-table`). `columns` is `{ field, label?, glyph?, unit?, format?, max?, icon? }[]`. |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"blueprint"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `1100` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [shape-fill](https://insightcharts.dev/llms/shape-fill.md), [scale-ladder](https://insightcharts.dev/llms/scale-ladder.md), [glyph-table](https://insightcharts.dev/llms/glyph-table.md)
- Used by: no molecule or template yet

### More examples

#### Dusk, a reservoir, depths read downwards, linked

```tsx
import { ProfilePoster } from "insightcharts";

<ProfilePoster
  theme="dusk"
  linked
  kicker="Water supply"
  title="Carrow Reservoir was 63% full on 1 September 2025"
  subtitle="Water stored in Carrow Reservoir as a share of its 65 million cubic metre capacity."
  portrait={{
    data: [{ reservoir: "Carrow", full: 63 }],
    name: "reservoir",
    value: "full",
    icon: "drop",
    title: "Share of capacity in store",
  }}
  figures={[
    { value: "41 million", label: "cubic metres of water were in store" },
    { value: "212,000", label: "homes take their water from it" },
    { value: "9 m", label: "below the spillway was the water level" },
  ]}
  scale={{
    data: [
      { level: "Spillway crest", m: 0, icon: "wave" },
      { level: "Water on 1 September", m: 9, icon: "drop" },
      { level: "Upper intake", m: 14, icon: "pin" },
      { level: "Lower intake", m: 31, icon: "pin" },
      { level: "Old mill bridge", m: 38, icon: "building" },
      { level: "Reservoir floor", m: 52, icon: "mountain" },
    ],
    name: "level",
    value: "m",
    iconField: "icon",
    direction: "down",
    min: 0,
    max: 60,
    format: "{value} m",
    scaleLabel: "Depth below the spillway, m",
    highlight: "Water on 1 September",
    title: "The lower intake is 31 m below the spillway",
  }}
  table={{
    rows: [
      { reservoir: "Carrow", full: 63, stored: 41, homes: 212, age: 71 },
      { reservoir: "Upper Fen", full: 41, stored: 12, homes: 64, age: 38 },
      { reservoir: "Stonebeck", full: 88, stored: 57, homes: 188, age: 54 },
      { reservoir: "Hollin Moss", full: 72, stored: 23, homes: 97, age: 102 },
    ],
    name: "reservoir",
    nameLabel: "Reservoir",
    title: "Stonebeck Reservoir was 88% full on the same day",
    columns: [
      { field: "full", label: "Share of capacity", glyph: "ring", format: "{value}%" },
      { field: "stored", label: "Water in store, million m³", glyph: "circle" },
      {
        field: "homes",
        label: "Homes supplied, thousands",
        glyph: "icons",
        icon: "house",
        unit: 20,
      },
      { field: "age", label: "Age, years", glyph: "bar" },
    ],
  }}
  sources="Carrow Water, reservoir levels bulletin"
  note="Carrow Water and its reservoirs are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Paper, a wind turbine, no table, with download

```tsx
import { ProfilePoster } from "insightcharts";

<ProfilePoster
  theme="paper"
  download
  kicker="Wind power"
  title="The Aldern turbine ran at 38% of its full output in 2025"
  subtitle="Electricity generated by one 4.2 MW turbine as a share of its output at full power all year."
  portrait={{
    data: [{ measure: "Capacity factor, 2025", share: 38 }],
    name: "measure",
    value: "share",
    icon: "wind-turbine",
    title: "Share of full output",
  }}
  figures={[
    { value: "14 GWh", label: "of electricity generated in 2025" },
    { value: "3,700", label: "homes' use of electricity for a year" },
  ]}
  scale={{
    data: [
      { thing: "Oak tree", m: 24, icon: "tree" },
      { thing: "Electricity pylon", m: 50, icon: "bolt" },
      { thing: "Aldern church spire", m: 62, icon: "building" },
      { thing: "Turbine hub", m: 105, icon: "wind-turbine" },
      { thing: "Turbine blade tip", m: 170, icon: "wind-turbine" },
    ],
    name: "thing",
    value: "m",
    iconField: "icon",
    min: 0,
    max: 200,
    format: "{value} m",
    scaleLabel: "Height, m",
    highlight: ["Turbine hub", "Turbine blade tip"],
    title: "The blade tip reaches 170 m",
  }}
  sources="Aldern Community Energy, generation report 2025"
  note="Aldern Community Energy is invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/profile-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/profile-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Radial poster (`radial-poster`)

> A poster with one subject in the middle of the sheet: a wheel of spokes round an icon (`radial-spokes`), two to four large figures standing either side of it, and a bottom row with the same subject's surroundings on concentric rings (`orbit-chart`) and a ranking as centred pills (`pill-rank`).

- Component: `RadialPoster` (import from `insightcharts`)
- Spec type: `"radial-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when the poster is about the 4 to 12 parts, causes, effects or scores of one thing: what a household's water goes on, the species one tree supports, where one home's energy goes. Give `hero` the spokes and an `icon` for the centre, state the total in the title, and use `figures` for the two to four numbers a reader should take away.

### Avoid

Parts of a whole that must be compared precisely (use `bar-chart` in a `poster`). Positions on one scale (use `scale-poster`). Change over time (use `timeline-poster`). Connections between many things (use `network-poster`). Large counts shown as crowds (use `count-poster`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/radial-poster
```

The file lands at `components/insightcharts/templates/radial-poster.tsx`. `@insightcharts/radial-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { RadialPoster } from "insightcharts";

<RadialPoster
  theme="magenta"
  kicker="Water"
  title="A person on Verne Street used 142 litres of water a day in 2025"
  subtitle="Litres of mains water per person per day by use, 212 metered homes, 2025."
  hero={{
    data: [
      { use: "Shower", litres: 44 },
      { use: "Toilet", litres: 31 },
      { use: "Washing machine", litres: 19 },
      { use: "Kitchen tap", litres: 17 },
      { use: "Garden", litres: 12 },
      { use: "Dishwasher", litres: 9 },
      { use: "Bath", litres: 6 },
      { use: "Other", litres: 4 },
    ],
    name: "use",
    value: "litres",
    icon: "drop",
    format: "{value} L",
    highlight: "Shower",
  }}
  figures={[
    { value: "44 L", label: "went on showers", context: "31% of the daily total" },
    { value: "9 min", label: "was the average length of a shower" },
    { value: "6 L", label: "went on baths" },
    { value: "€1.12", label: "was the cost of one person's water for a day" },
  ]}
  rings={{
    data: [
      { fixture: "Bath", room: "Bathroom", litres: 80 },
      { fixture: "Shower, 8 min", room: "Bathroom", litres: 64 },
      { fixture: "Toilet flush", room: "Bathroom", litres: 6 },
      { fixture: "Washing machine", room: "Kitchen", litres: 50 },
      { fixture: "Dishwasher", room: "Kitchen", litres: 12 },
      { fixture: "Washing-up bowl", room: "Kitchen", litres: 8 },
      { fixture: "Hose, 10 min", room: "Garden", litres: 150 },
      { fixture: "Watering can", room: "Garden", litres: 10 },
    ],
    name: "fixture",
    ring: "room",
    value: "litres",
    format: "{value} L",
    icon: "house",
    ringLabel: "One ring per room",
    sizeLabel: "litres per use",
    highlight: "Hose, 10 min",
    title: "Ten minutes with a hose used 150 litres",
    height: 460,
  }}
  rank={{
    data: [
      { district: "Harbour", litres: 168 },
      { district: "Old Town", litres: 155 },
      { district: "Verne Street", litres: 142 },
      { district: "Northgate", litres: 136 },
      { district: "Riverside", litres: 129 },
      { district: "Mill Lane", litres: 117 },
    ],
    name: "district",
    value: "litres",
    format: "{value} L",
    highlight: "Verne Street",
    title: "Verne Street ranked third of six districts",
  }}
  sources="Verne Street metering study 2025"
  note="Verne Street and its figures are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "radial-poster",
  "theme": "magenta",
  "kicker": "Water",
  "title": "A person on Verne Street used 142 litres of water a day in 2025",
  "subtitle": "Litres of mains water per person per day by use, 212 metered homes, 2025.",
  "hero": {
    "data": [
      { "use": "Shower", "litres": 44 },
      { "use": "Toilet", "litres": 31 },
      { "use": "Washing machine", "litres": 19 },
      { "use": "Kitchen tap", "litres": 17 },
      { "use": "Garden", "litres": 12 },
      { "use": "Dishwasher", "litres": 9 },
      { "use": "Bath", "litres": 6 },
      { "use": "Other", "litres": 4 }
    ],
    "name": "use",
    "value": "litres",
    "icon": "drop",
    "format": "{value} L",
    "highlight": "Shower"
  },
  "figures": [
    { "value": "44 L", "label": "went on showers", "context": "31% of the daily total" },
    { "value": "9 min", "label": "was the average length of a shower" },
    { "value": "6 L", "label": "went on baths" },
    { "value": "€1.12", "label": "was the cost of one person's water for a day" }
  ],
  "rings": {
    "data": [
      { "fixture": "Bath", "room": "Bathroom", "litres": 80 },
      { "fixture": "Shower, 8 min", "room": "Bathroom", "litres": 64 },
      { "fixture": "Toilet flush", "room": "Bathroom", "litres": 6 },
      { "fixture": "Washing machine", "room": "Kitchen", "litres": 50 },
      { "fixture": "Dishwasher", "room": "Kitchen", "litres": 12 },
      { "fixture": "Washing-up bowl", "room": "Kitchen", "litres": 8 },
      { "fixture": "Hose, 10 min", "room": "Garden", "litres": 150 },
      { "fixture": "Watering can", "room": "Garden", "litres": 10 }
    ],
    "name": "fixture",
    "ring": "room",
    "value": "litres",
    "format": "{value} L",
    "icon": "house",
    "ringLabel": "One ring per room",
    "sizeLabel": "litres per use",
    "highlight": "Hose, 10 min",
    "title": "Ten minutes with a hose used 150 litres",
    "height": 460
  },
  "rank": {
    "data": [
      { "district": "Harbour", "litres": 168 },
      { "district": "Old Town", "litres": 155 },
      { "district": "Verne Street", "litres": 142 },
      { "district": "Northgate", "litres": 136 },
      { "district": "Riverside", "litres": 129 },
      { "district": "Mill Lane", "litres": 117 }
    ],
    "name": "district",
    "value": "litres",
    "format": "{value} L",
    "highlight": "Verne Street",
    "title": "Verne Street ranked third of six districts"
  },
  "sources": "Verne Street metering study 2025",
  "note": "Verne Street and its figures are invented. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `hero` (required) | `{ data, name, value, icon?, centerLabel?, shape?, sweep?, max?, highlight?, format?, title?, ... } \| Slot` |  | The hero: one spoke per row round a centre disc, drawn by `radial-spokes`. A full spec or element replaces it. |
| `figures` | `{ value: string; label: string; context?: string; icon?: string; tag?: string }[]` |  | Two to four large figures. On a sheet at least 960px wide they stand in two columns either side of the hero; on a narrower one they run in a row under it. |
| `rings` | `{ data, name, ring, value?, rings?, ringLabel?, sizeLabel?, icon?, centerLabel?, title?, ... } \| Slot` |  | Bottom left: named things on concentric rings, one ring per category, level or period (`orbit-chart`). |
| `rank` | `{ data, name, value, highlight?, compare?, format?, title?, ... } \| Slot` |  | Bottom right: a ranking as centred pills (`pill-rank`). With only one of `rings` and `rank`, that one takes the full width. |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"magenta"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `1100` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [radial-spokes](https://insightcharts.dev/llms/radial-spokes.md), [orbit-chart](https://insightcharts.dev/llms/orbit-chart.md), [pill-rank](https://insightcharts.dev/llms/pill-rank.md)
- Used by: no molecule or template yet

### More examples

#### Forest, one tree, no rings, with download

```tsx
import { RadialPoster } from "insightcharts";

<RadialPoster
  theme="forest"
  download
  kicker="Woodland"
  title="One oak in Halden Wood supported 284 species in 2025"
  subtitle="Species recorded on a single 180-year-old oak by group, April to September 2025."
  hero={{
    data: [
      { group: "Insects", species: 126 },
      { group: "Lichens", species: 58 },
      { group: "Fungi", species: 41 },
      { group: "Birds", species: 23 },
      { group: "Mosses", species: 19 },
      { group: "Mammals", species: 11 },
      { group: "Spiders", species: 6 },
    ],
    name: "group",
    value: "species",
    icon: "tree",
    shape: "line",
    highlight: "Insects",
  }}
  figures={[
    { value: "126", label: "of the 284 species were insects" },
    { value: "180", label: "years is the age of the tree" },
    { value: "23", label: "bird species fed or nested on it" },
    { value: "58", label: "lichens grew on its bark" },
  ]}
  rank={{
    data: [
      { tree: "Oak", species: 284 },
      { tree: "Willow", species: 251 },
      { tree: "Birch", species: 229 },
      { tree: "Hawthorn", species: 149 },
      { tree: "Beech", species: 98 },
      { tree: "Ash", species: 68 },
    ],
    name: "tree",
    value: "species",
    highlight: "Oak",
    title: "Willow supported 251 species",
  }}
  sources="Halden Wood survey 2025"
  note="Halden Wood is an invented place. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Noir, a half wheel, linked to the ranking

```tsx
import { RadialPoster } from "insightcharts";

<RadialPoster
  theme="noir"
  linked
  kicker="Home energy"
  title="Heating took 5,900 of the 11,400 kWh one Carrow house used in 2025"
  subtitle="Electricity used by one all-electric house by end use, kilowatt-hours, 2025."
  hero={{
    data: [
      { use: "Heating", kwh: 5900 },
      { use: "Hot water", kwh: 2100 },
      { use: "Car charging", kwh: 1800 },
      { use: "Appliances", kwh: 900 },
      { use: "Cooking", kwh: 450 },
      { use: "Lighting", kwh: 250 },
    ],
    name: "use",
    value: "kwh",
    icon: "house",
    sweep: 180,
    startAngle: -90,
    format: "{value} kWh",
  }}
  figures={[
    { value: "52%", label: "of the electricity went on heating" },
    { value: "€2,514", label: "was the electricity bill for the year" },
  ]}
  rank={{
    data: [
      { use: "Heating", eur: 1298 },
      { use: "Hot water", eur: 462 },
      { use: "Car charging", eur: 306 },
      { use: "Appliances", eur: 252 },
      { use: "Cooking", eur: 126 },
      { use: "Lighting", eur: 70 },
    ],
    name: "use",
    value: "eur",
    format: "€{value}",
    title: "Heating cost €1,298 of the €2,514",
  }}
  sources="Carrow house smart-meter export"
  note="The Carrow house is invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/radial-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/radial-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Ranking poster (`ranking-poster`)

> A 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.

- Component: `RankingPoster` (import from `insightcharts`)
- Spec type: `"ranking-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for a profile of one event, place or organisation that has a headline total, two ways to split it, a ranking of 6 to 12 named things and a few supporting magnitudes: a festival, a race, a nature reserve, a library service. Put the total in the title and repeat it as the first figure. Highlight the ranking row the heading is about.

### Avoid

A subject whose point is a count of people or things (use `count-poster`). Several entities compared on the same measures (use `matrix-poster`). Eight or more small graphics on one subject (use `atlas-poster`). A ranking alone (use `pill-rank` in a `poster`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/ranking-poster
```

The file lands at `components/insightcharts/templates/ranking-poster.tsx`. `@insightcharts/ranking-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { RankingPoster } from "insightcharts";

<RankingPoster
  theme="dusk"
  kicker="Music"
  title="The Solvik Festival sold 184,000 tickets in 2025"
  subtitle="Tickets, crowds and spending at a three-day music festival, 11 to 13 July 2025."
  figures={[
    { value: "184,000", label: "Tickets sold in 2025", context: "171,000 in 2024" },
    {
      data: [{ day: "Friday", share: 84 }, { day: "Saturday", share: 100 }, { day: "Sunday", share: 91 }],
      name: "day",
      value: "share",
      icon: "group",
      title: "Saturday sold 100% of its 64,000 places",
    },
  ]}
  breakdowns={[
    {
      data: [
        { ticket: "Weekend pass", k: 92 },
        { ticket: "Day ticket", k: 61 },
        { ticket: "Camping pass", k: 23 },
        { ticket: "VIP pass", k: 8 },
      ],
      name: "ticket",
      value: "k",
      format: "{value}k",
      title: "92,000 tickets were weekend passes",
    },
    {
      data: [
        { home: "Solvik region", k: 71 },
        { home: "Rest of the country", k: 64 },
        { home: "Neighbouring countries", k: 37 },
        { home: "Further away", k: 12 },
      ],
      name: "home",
      value: "k",
      format: "{value}k",
      title: "71,000 ticket holders lived in the Solvik region",
    },
  ]}
  ranking={{
    data: [
      { act: "Halden Lights", crowd: 61000 },
      { act: "Mirra Sol", crowd: 58500 },
      { act: "The Quiet Engines", crowd: 52000 },
      { act: "Ada Vance", crowd: 47500 },
      { act: "Northfold", crowd: 41000 },
      { act: "Juno Marsh", crowd: 36500 },
      { act: "Saltwater Choir", crowd: 31000 },
      { act: "Okapi Club", crowd: 26500 },
      { act: "Tess Arden", crowd: 22000 },
      { act: "Low Tide Radio", crowd: 17500 },
    ],
    name: "act",
    value: "crowd",
    format: "integer",
    highlight: "Halden Lights",
    title: "Halden Lights played to 61,000 people on Saturday",
    subtitle: "Largest crowd at each of the ten most-attended acts",
  }}
  pack={{
    data: [
      { item: "Food stalls", k: 3400 },
      { item: "Beer", k: 2900 },
      { item: "Merchandise", k: 2300 },
      { item: "Wine and cocktails", k: 1600 },
      { item: "Soft drinks", k: 1100 },
      { item: "Camping shop", k: 900 },
      { item: "Coffee", k: 700 },
      { item: "Lockers and charging", k: 500 },
      { item: "Water", k: 400 },
      { item: "Ice cream", k: 400 },
    ],
    name: "item",
    value: "k",
    format: "€{value}k",
    icon: {
      "Food stalls": "fork-knife",
      Beer: "cup",
      Merchandise: "bag",
      "Wine and cocktails": "bottle",
      "Soft drinks": "bottle",
      "Camping shop": "cart",
      Coffee: "cup",
    },
    title: "Visitors spent €3.4 million at food stalls",
    subtitle: "Spending on site by category, thousand euros",
  }}
  circles={{
    data: [
      { year: "per visitor in 2019", kg: 2.6 },
      { year: "per visitor in 2022", kg: 1.9 },
      { year: "per visitor in 2025", kg: 1.2 },
    ],
    name: "year",
    value: "kg",
    unit: "kg",
    title: "Each visitor left 1.2 kg of waste in 2025",
  }}
  figure={{
    value: "€14.2m",
    label: "Spent on site by visitors in 2025",
    context: "€77 for each ticket sold",
  }}
  sources="Solvik Festival annual report 2025"
  note="The Solvik Festival and its acts are invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "ranking-poster",
  "theme": "dusk",
  "kicker": "Music",
  "title": "The Solvik Festival sold 184,000 tickets in 2025",
  "subtitle": "Tickets, crowds and spending at a three-day music festival, 11 to 13 July 2025.",
  "figures": [
    { "value": "184,000", "label": "Tickets sold in 2025", "context": "171,000 in 2024" },
    {
      "data": [
        { "day": "Friday", "share": 84 },
        { "day": "Saturday", "share": 100 },
        { "day": "Sunday", "share": 91 }
      ],
      "name": "day",
      "value": "share",
      "icon": "group",
      "title": "Saturday sold 100% of its 64,000 places"
    }
  ],
  "breakdowns": [
    {
      "data": [
        { "ticket": "Weekend pass", "k": 92 },
        { "ticket": "Day ticket", "k": 61 },
        { "ticket": "Camping pass", "k": 23 },
        { "ticket": "VIP pass", "k": 8 }
      ],
      "name": "ticket",
      "value": "k",
      "format": "{value}k",
      "title": "92,000 tickets were weekend passes"
    },
    {
      "data": [
        { "home": "Solvik region", "k": 71 },
        { "home": "Rest of the country", "k": 64 },
        { "home": "Neighbouring countries", "k": 37 },
        { "home": "Further away", "k": 12 }
      ],
      "name": "home",
      "value": "k",
      "format": "{value}k",
      "title": "71,000 ticket holders lived in the Solvik region"
    }
  ],
  "ranking": {
    "data": [
      { "act": "Halden Lights", "crowd": 61000 },
      { "act": "Mirra Sol", "crowd": 58500 },
      { "act": "The Quiet Engines", "crowd": 52000 },
      { "act": "Ada Vance", "crowd": 47500 },
      { "act": "Northfold", "crowd": 41000 },
      { "act": "Juno Marsh", "crowd": 36500 },
      { "act": "Saltwater Choir", "crowd": 31000 },
      { "act": "Okapi Club", "crowd": 26500 },
      { "act": "Tess Arden", "crowd": 22000 },
      { "act": "Low Tide Radio", "crowd": 17500 }
    ],
    "name": "act",
    "value": "crowd",
    "format": "integer",
    "highlight": "Halden Lights",
    "title": "Halden Lights played to 61,000 people on Saturday",
    "subtitle": "Largest crowd at each of the ten most-attended acts"
  },
  "pack": {
    "data": [
      { "item": "Food stalls", "k": 3400 },
      { "item": "Beer", "k": 2900 },
      { "item": "Merchandise", "k": 2300 },
      { "item": "Wine and cocktails", "k": 1600 },
      { "item": "Soft drinks", "k": 1100 },
      { "item": "Camping shop", "k": 900 },
      { "item": "Coffee", "k": 700 },
      { "item": "Lockers and charging", "k": 500 },
      { "item": "Water", "k": 400 },
      { "item": "Ice cream", "k": 400 }
    ],
    "name": "item",
    "value": "k",
    "format": "€{value}k",
    "icon": {
      "Food stalls": "fork-knife",
      "Beer": "cup",
      "Merchandise": "bag",
      "Wine and cocktails": "bottle",
      "Soft drinks": "bottle",
      "Camping shop": "cart",
      "Coffee": "cup"
    },
    "title": "Visitors spent €3.4 million at food stalls",
    "subtitle": "Spending on site by category, thousand euros"
  },
  "circles": {
    "data": [
      { "year": "per visitor in 2019", "kg": 2.6 },
      { "year": "per visitor in 2022", "kg": 1.9 },
      { "year": "per visitor in 2025", "kg": 1.2 }
    ],
    "name": "year",
    "value": "kg",
    "unit": "kg",
    "title": "Each visitor left 1.2 kg of waste in 2025"
  },
  "figure": {
    "value": "€14.2m",
    "label": "Spent on site by visitors in 2025",
    "context": "€77 for each ticket sold"
  },
  "sources": "Solvik Festival annual report 2025",
  "note": "The Solvik Festival and its acts are invented. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `figures` | `({ value, label, context?, icon? } \| { data, name, value, icon, title?, ...shape-fill props } \| Slot)[]` |  | Top row, up to two. A statement `{ value, label }` is set in large light type (the first in the accent colour); a config with `data` draws silhouettes filled to their level (`shape-fill`). |
| `breakdowns` | `({ data, name, value, title?, ...treemap props } \| Slot)[]` |  | Second row, up to two: the subject's total split two ways, as treemaps side by side. |
| `ranking` (required) | `{ data, name, value, highlight?, compare?, compareLabel?, title?, ...pill-rank props } \| Slot` |  | Third row, full width: a ranking as centred pills with the value at the left and the rank at the right (`pill-rank`). `highlight` names the row drawn in the accent. |
| `pack` | `{ data, name, value, icon?, group?, title?, ...circle-pack props } \| Slot` |  | Bottom left: parts as packed circles (`circle-pack`). `icon` is one icon name or a map from circle name to icon. |
| `circles` | `{ data, name, value, unit?, title?, ...stat-circles props } \| Slot` |  | Bottom right: two to four related magnitudes as circles standing on one baseline (`stat-circles`). |
| `figure` | `{ value, label, context?, icon? }` |  | Bottom right, under the circles: one closing figure in large type. |
| `format` | `FormatSpec` |  | How to print values in the regions that set no `format` of their own. |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"dusk"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `1100` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [shape-fill](https://insightcharts.dev/llms/shape-fill.md), [treemap](https://insightcharts.dev/llms/treemap.md), [pill-rank](https://insightcharts.dev/llms/pill-rank.md), [circle-pack](https://insightcharts.dev/llms/circle-pack.md), [stat-circles](https://insightcharts.dev/llms/stat-circles.md)
- Used by: no molecule or template yet

### More examples

#### Paper, a road race, two statements

```tsx
import { RankingPoster } from "insightcharts";

<RankingPoster
  theme="paper"
  kicker="Sport"
  title="The Harrow Valley Half Marathon had 18,400 finishers in 2025"
  subtitle="Finishers, running clubs and money raised at the race on 5 October 2025."
  figures={[
    { value: "18,400", label: "Finishers in 2025", context: "16,900 in 2024", icon: "flag" },
    {
      value: "1:58",
      label: "Median finishing time in hours and minutes",
      context: "2:01 in 2024",
      icon: "clock",
    },
  ]}
  breakdowns={[
    {
      data: [
        { age: "Under 30", runners: 4300 },
        { age: "30 to 39", runners: 5900 },
        { age: "40 to 49", runners: 4600 },
        { age: "50 to 59", runners: 2500 },
        { age: "60 and over", runners: 1100 },
      ],
      name: "age",
      value: "runners",
      format: "integer",
      title: "5,900 finishers were aged 30 to 39",
    },
    {
      data: [
        { home: "Harrow Valley", runners: 7900 },
        { home: "Rest of the county", runners: 5200 },
        { home: "Elsewhere in the country", runners: 4400 },
        { home: "Abroad", runners: 900 },
      ],
      name: "home",
      value: "runners",
      format: "integer",
      title: "7,900 finishers lived in the Harrow Valley",
    },
  ]}
  ranking={{
    data: [
      { club: "Harrow Harriers", runners: 412 },
      { club: "Millbrook AC", runners: 356 },
      { club: "Castle Runners", runners: 298 },
      { club: "Valley Striders", runners: 271 },
      { club: "Eastfield Joggers", runners: 233 },
      { club: "Ridgeway RC", runners: 187 },
      { club: "Canal Path Runners", runners: 164 },
      { club: "Old Mill Milers", runners: 129 },
    ],
    name: "club",
    value: "runners",
    format: "integer",
    highlight: "Harrow Harriers",
    title: "Harrow Harriers had 412 finishers",
    subtitle: "Finishers by running club, the eight largest",
  }}
  pack={{
    data: [
      { cause: "Hospice care", k: 310 },
      { cause: "Children's hospital", k: 260 },
      { cause: "Mountain rescue", k: 150 },
      { cause: "Food bank", k: 140 },
      { cause: "Animal shelter", k: 120 },
      { cause: "School sports", k: 110 },
      { cause: "Tree planting", k: 90 },
      { cause: "Library fund", k: 60 },
      { cause: "Lifeboats", k: 60 },
    ],
    name: "cause",
    value: "k",
    format: "£{value}k",
    icon: {
      "Hospice care": "heart",
      "Children's hospital": "hospital",
      "Mountain rescue": "mountain",
      "Food bank": "bread",
      "School sports": "school",
      "Tree planting": "tree",
    },
    title: "Runners raised £310,000 for hospice care",
    subtitle: "Money raised by cause, thousand pounds",
  }}
  circles={{
    data: [
      { year: "finishers in 2015", runners: 9200 },
      { year: "finishers in 2020", runners: 12600 },
      { year: "finishers in 2025", runners: 18400 },
    ],
    name: "year",
    value: "runners",
    format: "integer",
    title: "The race had 9,200 finishers in 2015",
  }}
  figure={{ value: "£1.3m", label: "Raised for nine causes in 2025", context: "£71 for each finisher" }}
  sources="Harrow Valley Athletics race results and fundraising returns"
  note="The Harrow Valley Half Marathon is an invented race. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Ocean, a marine reserve, linked, with download

```tsx
import { RankingPoster } from "insightcharts";

<RankingPoster
  theme="ocean"
  linked
  download
  kicker="Oceans"
  title="Divers recorded 1,260 species in the Calder Reef reserve in 2025"
  subtitle="Species, sightings and visitors in a marine reserve, annual survey 2025."
  figures={[
    {
      value: "1,260",
      label: "Species recorded in 2025",
      context: "1,140 in the 2020 survey",
      icon: "fish",
    },
    {
      data: [{ zone: "Closed to fishing", share: 38 }],
      name: "zone",
      value: "share",
      icon: "lock",
      title: "38% of the reserve was closed to fishing",
    },
  ]}
  breakdowns={[
    {
      data: [
        { group: "Fish", species: 540 },
        { group: "Molluscs", species: 310 },
        { group: "Corals", species: 190 },
        { group: "Crustaceans", species: 150 },
        { group: "Other", species: 70 },
      ],
      name: "group",
      value: "species",
      format: "integer",
      title: "540 of the species were fish",
    },
    {
      data: [
        { habitat: "Reef crest", species: 430 },
        { habitat: "Lagoon", species: 350 },
        { habitat: "Seagrass beds", species: 260 },
        { habitat: "Deep slope", species: 220 },
      ],
      name: "habitat",
      value: "species",
      format: "integer",
      title: "430 species were first recorded on the reef crest",
    },
  ]}
  ranking={{
    data: [
      { fish: "Blue chromis", seen: 8400 },
      { fish: "Sergeant major", seen: 7100 },
      { fish: "Bluehead wrasse", seen: 6300 },
      { fish: "Yellowtail snapper", seen: 5200 },
      { fish: "Stoplight parrotfish", seen: 4100 },
      { fish: "French grunt", seen: 3600 },
      { fish: "Queen angelfish", seen: 1900 },
      { fish: "Nassau grouper", seen: 640 },
    ],
    name: "fish",
    value: "seen",
    format: "integer",
    highlight: "Nassau grouper",
    title: "Divers recorded 640 Nassau groupers",
    subtitle: "Sightings of eight fish species on survey dives",
  }}
  pack={{
    data: [
      { activity: "Beach visits", k: 120 },
      { activity: "Snorkelling", k: 86 },
      { activity: "Boat tours", k: 64 },
      { activity: "Scuba diving", k: 41 },
      { activity: "Kayaking", k: 28 },
      { activity: "School trips", k: 14 },
      { activity: "Research stays", k: 6 },
    ],
    name: "activity",
    value: "k",
    format: "{value}k",
    icon: {
      "Beach visits": "sun",
      Snorkelling: "wave",
      "Boat tours": "ship",
      "Scuba diving": "fish",
      Kayaking: "drop",
      "School trips": "school",
    },
    title: "120,000 people visited the reserve's beaches",
    subtitle: "Visitors by activity, thousands",
  }}
  circles={{
    data: [
      { year: "km² in 2005", km2: 140 },
      { year: "km² in 2015", km2: 310 },
      { year: "km² in 2025", km2: 520 },
    ],
    name: "year",
    value: "km2",
    format: "integer",
    title: "The reserve covered 520 km² in 2025",
  }}
  figure={{ value: "359,000", label: "Visitors in 2025", context: "312,000 in 2024" }}
  sources="Calder Reef Reserve annual survey 2025"
  note="The Calder Reef reserve is an invented place. Species are real; all figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/ranking-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/ranking-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Report page (`report-page`)

> A section of an analytical report laid out as a document. It has a title block, a summary, numbered findings, then method, limitations and sources. Each finding has one exhibit, an observation and a separately labelled interpretation with a confidence rating and a caveat.

- Component: `ReportPage` (import from `insightcharts`)
- Spec type: `"report-page"`
- Level: template. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for readers who will check the reasoning, as in evaluations, research notes, audits and experiment write-ups. State the main finding with its number in the title. Put all the main findings and the recommendation in the summary. Write each finding title as one fact with its number, and give it an exhibit that shows that fact. Put what the data shows in `observation` and what you infer from it in `interpretation`. End with method, limitations and sources.

### Avoid

A decision-maker who wants only the result (use `executive-brief`). A general audience (use `explainer` or `visual-essay`). Findings without an exhibit. Put those in the summary.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/report-page
```

The file lands at `components/insightcharts/templates/report-page.tsx`. `@insightcharts/report-page-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, ProgressMeter, ReportPage } from "insightcharts";

<ReportPage
  kicker="Small-group tutoring programme · Year 1 evaluation"
  title="Tutored pupils gained 2.9 more scaled-score points in maths than matched pupils"
  deck="The difference in reading was 0.5 points. 31% of tutored pupils were eligible for free school meals against a funding target of 50%."
  byline="Evaluation team"
  date="2025-02-20"
  summary="Pupils offered tutoring gained **2.9 more scaled-score points in maths** over the year than matched pupils who were not. That is about three months of additional learning. The difference in reading was 0.5 points and could be chance. Pupils who attended fewer than 12 sessions gained less than 1 point over their matches. 58% of pupils attended 12 or more. We recommend continuing the maths strand. Attendance should be the main delivery target. The way pupils are selected should change."
  findings={[
    {
      title: "Tutored pupils gained 8.1 points in maths against 5.2 for comparison pupils",
      exhibit: <BarChart
        data={[
          { subject: "Maths", Tutored: 8.1, Comparison: 5.2 },
          { subject: "Reading", Tutored: 5.9, Comparison: 5.4 },
        ]}
        x="subject"
        y={["Tutored", "Comparison"]}
        orientation="horizontal"
        sort="none"
        highlight="Tutored"
        format="decimal:1"
        subtitle="Mean gain in scaled score, autumn 2023 to summer 2024"
        source="Standardised assessments, 42 schools"
      />,
      observation: "The difference in maths was 2.9 points (95% interval 1.6 to 4.2). In reading tutored pupils gained 5.9 points and comparison pupils 5.4. That difference was 0.5 points (−0.7 to 1.7).",
      interpretation: "The maths difference is unlikely to be chance. Trials of similar programmes found effects of about the same size. We do not conclude that reading tutoring failed, because half the reading tutors were recruited after January.",
      confidence: "medium",
      caveat: "Pupils were matched on prior attainment and background. They were not randomised. Unmeasured differences, such as parental engagement, could account for part of the difference.",
    },
    {
      title: "Pupils who attended 18 or more sessions gained 4.4 points over their matches",
      exhibit: <BarChart
        data={[
          { sessions: "Under 6", effect: 0.2 },
          { sessions: "6–11", effect: 0.9 },
          { sessions: "12–17", effect: 3.1 },
          { sessions: "18+", effect: 4.4 },
        ]}
        x="sessions"
        y="effect"
        orientation="vertical"
        sort="none"
        format={{ signDisplay: "exceptZero", maximumFractionDigits: 1 }}
        height={260}
        subtitle="Maths gain over comparison pupils, scaled-score points, by sessions attended (of 20 offered)"
      />,
      observation: "Pupils who attended fewer than 6 sessions gained 0.2 points more than their matches. Those who attended 6 to 11 gained 0.9 points more. 42% of tutored pupils attended fewer than 12 sessions.",
      interpretation: "A gain that rises with attendance is consistent with a real effect. Pupils who attend more may also differ in ways that raise attainment. The effect of extra sessions is therefore probably smaller than the bars show.",
      confidence: "low",
    },
    {
      title: "31% of tutored pupils were eligible for free school meals against a target of 50%",
      exhibit: <ProgressMeter
        label="Tutored pupils eligible for free school meals"
        value={0.31}
        max={1}
        showMax={false}
        target={0.5}
        targetLabel="Funding target"
        format="percent"
        context="984 of 3,180 pupils. In the same schools, 38% of all pupils are eligible."
      />,
      observation: "984 of the 3,180 tutored pupils were eligible for free school meals. The funding agreement specifies 50%. 38% of all pupils in the participating schools are eligible.",
      interpretation: "Schools selected pupils by teacher nomination. Nomination appears to favour pupils just below the expected standard over the most disadvantaged. The schools have enough eligible pupils to meet the target, so we think the selection rules cause the shortfall.",
      confidence: "high",
    },
  ]}
  method="We compared 3,180 tutored pupils in 42 schools with 3,180 pupils in the same schools and year groups, matched one to one on prior attainment, free-school-meal eligibility, special educational needs and attendance in the previous year. Outcomes are scaled scores on the standardised assessments schools already use. Intervals are 95% and account for clustering by school."
  limitations={[
    "Matching cannot rule out differences we did not measure. A randomised design is planned for year two.",
    "Attendance was recorded by tutors and may be overstated.",
    "One year of outcomes does not show whether the gain lasts.",
  ]}
  sources={["School assessment returns", "Tutor session logs", "National pupil database extract"]}
  period="September 2023 to July 2024"
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "report-page",
  "kicker": "Small-group tutoring programme · Year 1 evaluation",
  "title": "Tutored pupils gained 2.9 more scaled-score points in maths than matched pupils",
  "deck": "The difference in reading was 0.5 points. 31% of tutored pupils were eligible for free school meals against a funding target of 50%.",
  "byline": "Evaluation team",
  "date": "2025-02-20",
  "summary": "Pupils offered tutoring gained **2.9 more scaled-score points in maths** over the year than matched pupils who were not. That is about three months of additional learning. The difference in reading was 0.5 points and could be chance. Pupils who attended fewer than 12 sessions gained less than 1 point over their matches. 58% of pupils attended 12 or more. We recommend continuing the maths strand. Attendance should be the main delivery target. The way pupils are selected should change.",
  "findings": [
    {
      "title": "Tutored pupils gained 8.1 points in maths against 5.2 for comparison pupils",
      "exhibit": {
        "type": "bar-chart",
        "data": [
          { "subject": "Maths", "Tutored": 8.1, "Comparison": 5.2 },
          { "subject": "Reading", "Tutored": 5.9, "Comparison": 5.4 }
        ],
        "x": "subject",
        "y": ["Tutored", "Comparison"],
        "orientation": "horizontal",
        "sort": "none",
        "highlight": "Tutored",
        "format": "decimal:1",
        "subtitle": "Mean gain in scaled score, autumn 2023 to summer 2024",
        "source": "Standardised assessments, 42 schools"
      },
      "observation": "The difference in maths was 2.9 points (95% interval 1.6 to 4.2). In reading tutored pupils gained 5.9 points and comparison pupils 5.4. That difference was 0.5 points (−0.7 to 1.7).",
      "interpretation": "The maths difference is unlikely to be chance. Trials of similar programmes found effects of about the same size. We do not conclude that reading tutoring failed, because half the reading tutors were recruited after January.",
      "confidence": "medium",
      "caveat": "Pupils were matched on prior attainment and background. They were not randomised. Unmeasured differences, such as parental engagement, could account for part of the difference."
    },
    {
      "title": "Pupils who attended 18 or more sessions gained 4.4 points over their matches",
      "exhibit": {
        "type": "bar-chart",
        "data": [
          { "sessions": "Under 6", "effect": 0.2 },
          { "sessions": "6–11", "effect": 0.9 },
          { "sessions": "12–17", "effect": 3.1 },
          { "sessions": "18+", "effect": 4.4 }
        ],
        "x": "sessions",
        "y": "effect",
        "orientation": "vertical",
        "sort": "none",
        "format": { "signDisplay": "exceptZero", "maximumFractionDigits": 1 },
        "height": 260,
        "subtitle": "Maths gain over comparison pupils, scaled-score points, by sessions attended (of 20 offered)"
      },
      "observation": "Pupils who attended fewer than 6 sessions gained 0.2 points more than their matches. Those who attended 6 to 11 gained 0.9 points more. 42% of tutored pupils attended fewer than 12 sessions.",
      "interpretation": "A gain that rises with attendance is consistent with a real effect. Pupils who attend more may also differ in ways that raise attainment. The effect of extra sessions is therefore probably smaller than the bars show.",
      "confidence": "low"
    },
    {
      "title": "31% of tutored pupils were eligible for free school meals against a target of 50%",
      "exhibit": {
        "type": "progress-meter",
        "label": "Tutored pupils eligible for free school meals",
        "value": 0.31,
        "max": 1,
        "showMax": false,
        "target": 0.5,
        "targetLabel": "Funding target",
        "format": "percent",
        "context": "984 of 3,180 pupils. In the same schools, 38% of all pupils are eligible."
      },
      "observation": "984 of the 3,180 tutored pupils were eligible for free school meals. The funding agreement specifies 50%. 38% of all pupils in the participating schools are eligible.",
      "interpretation": "Schools selected pupils by teacher nomination. Nomination appears to favour pupils just below the expected standard over the most disadvantaged. The schools have enough eligible pupils to meet the target, so we think the selection rules cause the shortfall.",
      "confidence": "high"
    }
  ],
  "method": "We compared 3,180 tutored pupils in 42 schools with 3,180 pupils in the same schools and year groups, matched one to one on prior attainment, free-school-meal eligibility, special educational needs and attendance in the previous year. Outcomes are scaled scores on the standardised assessments schools already use. Intervals are 95% and account for clustering by school.",
  "limitations": [
    "Matching cannot rule out differences we did not measure. A randomised design is planned for year two.",
    "Attendance was recorded by tutors and may be overstated.",
    "One year of outcomes does not show whether the gain lasts."
  ],
  "sources": ["School assessment returns", "Tutor session logs", "National pupil database extract"],
  "period": "September 2023 to July 2024",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The report's main finding, as one plain sentence with the number in it. |
| `kicker` | `string` |  | The report series or section, e.g. "Evaluation report · Section 3". |
| `deck` | `string` |  | One-sentence standfirst. |
| `byline` | `string` |  | Author line. |
| `date` | `string` |  | Publication date. |
| `summary` | `string \| string[]` |  | One paragraph with the main findings, their numbers and the recommendation. Supports `**bold**`. |
| `summaryTitle` | `string` | `"Summary"` | Heading of the summary. |
| `findings` | `{ title, exhibit?, observation?, interpretation?, confidence?: "high" \| "medium" \| "low", caveat?, id? }[]` |  | Numbered findings. `observation` is what the data shows; `interpretation` is what the authors infer, with an optional confidence rating and caveat. |
| `observationLabel` | `string` | `"What the data shows"` | Label over each observation. |
| `interpretationLabel` | `string` | `"What we think it means"` | Label over each interpretation. |
| `method` | `string \| string[]` |  | How the analysis was done, as its own section. |
| `limitations` | `string[]` |  | What the analysis cannot show. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `maxWidth` | `number \| string` |  | Widest the piece may get. It is centred in wider containers. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [prose](https://insightcharts.dev/llms/prose.md), [source-note](https://insightcharts.dev/llms/source-note.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [progress-meter](https://insightcharts.dev/llms/progress-meter.md), [line-chart](https://insightcharts.dev/llms/line-chart.md)
- Used by: no molecule or template yet

### More examples

#### Product analytics: an experiment write-up

```tsx
import { BarChart, LineChart, ReportPage } from "insightcharts";

<ReportPage
  kicker="Experiment PRC-114 · pricing page"
  title="The annual-first pricing page converted 3.4% of visitors against 3.1% for the control"
  byline="Growth analytics"
  date="2025-05-06"
  summary="Over six weeks the annual-first pricing page converted **3.4% of visitors**. The control converted 3.1%. 52% of new customers on the annual-first page chose annual billing, against 29% in the control. We recommend shipping the annual-first page. Track refund requests for two more months before counting the revenue."
  findings={[
    {
      title: "The annual-first page converted more visitors than the control in weeks 2 to 6",
      exhibit: <LineChart
        data={[
          { week: "Week 1", Control: 3.1, "Annual-first": 3 },
          { week: "Week 2", Control: 3.2, "Annual-first": 3.3 },
          { week: "Week 3", Control: 3, "Annual-first": 3.4 },
          { week: "Week 4", Control: 3.1, "Annual-first": 3.5 },
          { week: "Week 5", Control: 3.2, "Annual-first": 3.5 },
          { week: "Week 6", Control: 3.1, "Annual-first": 3.6 },
        ]}
        x="week"
        y={["Annual-first", "Control"]}
        highlight="Annual-first"
        format="{value}%"
        height={260}
        subtitle="Share of pricing-page visitors starting a paid plan, by week of first visit"
      />,
      observation: "The six-week mean was 3.38% for the annual-first page and 3.12% for the control. That is a relative lift of 8.5%. Each arm had 61,000 visitors.",
      interpretation: "The difference did not shrink after week 2, so we do not think it is a novelty effect. We are confident the annual-first page converts better. We are less sure of the size of the lift.",
      confidence: "high",
    },
    {
      title: "52% of new customers on the annual-first page chose annual billing",
      exhibit: <BarChart
        data={[
          { arm: "Control", Monthly: 71, Annual: 29 },
          { arm: "Annual-first", Monthly: 48, Annual: 52 },
        ]}
        x="arm"
        y={["Monthly", "Annual"]}
        stack="percent"
        orientation="horizontal"
        sort="none"
        highlight="Annual"
        format="{value}%"
        subtitle="Billing period chosen by new paying customers"
      />,
      observation: "52% of new customers in the annual-first arm chose annual billing. In the control 29% did.",
      interpretation: "More cash is collected up front. Annual customers who would have cancelled a monthly plan may ask for a refund instead. The effect on revenue will not be known until the 60-day refund window closes.",
      confidence: "medium",
      caveat: "Refunds within 60 days are not yet observable for weeks four to six.",
    },
  ]}
  method="Visitors were assigned at random by account cookie, 50/50, from 17 March to 27 April 2025. The primary metric, paid conversion within seven days, was registered before launch."
  limitations={[
    "Enterprise leads, who do not use the pricing page, are excluded.",
    "The test ran outside the January budget season, when annual plans usually sell better.",
  ]}
  sources={["Experiment platform", "Billing system"]}
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/report-page.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/report-page.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Scale poster (`scale-poster`)

> 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.

- Component: `ScalePoster` (import from `insightcharts`)
- Spec type: `"scale-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when the positions of 6 to about 16 named things on one scale are the whole subject: depths, altitudes, temperatures, distances, ages. Give the scale's rows and zones in `scale`, up to five `figures` with the scale position each belongs to, and optionally a `side` graphic of two to four magnitudes. Beside the scale the figures line up with their positions; under 760px they move below it.

### Avoid

Comparing sizes rather than positions (use `ranking-poster` or `count-poster`); change over time (use `timeline-poster`); more than about 16 items, because the labels run together; several unrelated graphics (use `poster` and lay the panels out yourself).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/scale-poster
```

The file lands at `components/insightcharts/templates/scale-poster.tsx`. `@insightcharts/scale-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { ScalePoster } from "insightcharts";

<ScalePoster
  theme="ocean"
  kicker="Oceans"
  title="The Meridian Deep survey logged 12 sightings between 8 m and 3,750 m"
  subtitle="Depth of each sighting on one research dive, metres below the surface."
  scale={{
    data: [
      { sighting: "Survey ship hull", m: 8, icon: "ship" },
      { sighting: "Kelp canopy", m: 120, icon: "leaf" },
      { sighting: "Sardine shoal", m: 310, icon: "fish" },
      { sighting: "Lanternfish layer", m: 560, icon: "fish" },
      { sighting: "Swordfish", m: 820, icon: "fish" },
      { sighting: "Coral mound", m: 1150, icon: "tree" },
      { sighting: "Sperm whale", m: 1480, icon: "wave" },
      { sighting: "Anglerfish", m: 1900, icon: "fish" },
      { sighting: "Sensor array", m: 2300, icon: "satellite" },
      { sighting: "Dumbo octopus", m: 2750, icon: "star" },
      { sighting: "Sea cucumbers", m: 3200, icon: "circle" },
      { sighting: "Seabed lander", m: 3750, icon: "pin" },
    ],
    name: "sighting",
    value: "m",
    iconField: "icon",
    direction: "down",
    min: 0,
    max: 4000,
    format: "{value} m",
    scaleLabel: "Depth, metres",
    zones: [
      { from: 0, to: 200, label: "Sunlit" },
      { from: 200, to: 1000, label: "Twilight zone" },
      { from: 1000, to: 4000, label: "Dark zone" },
    ],
  }}
  figures={[
    { at: 200, value: "1%", label: "of surface light is left" },
    { at: 1000, value: "4°C", label: "water temperature" },
    { at: 3000, value: "376 atm", label: "pressure at the lander, 3,750 m down" },
  ]}
  side={{
    data: [
      { zone: "species in the sunlit zone", species: 148 },
      { zone: "species in the twilight zone", species: 61 },
      { zone: "species in the dark zone", species: 23 },
    ],
    name: "zone",
    value: "species",
    title: "Species logged",
    height: 250,
  }}
  sideAt={1900}
  sources="Meridian Deep survey log"
  note="The Meridian Deep survey is invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "scale-poster",
  "theme": "ocean",
  "kicker": "Oceans",
  "title": "The Meridian Deep survey logged 12 sightings between 8 m and 3,750 m",
  "subtitle": "Depth of each sighting on one research dive, metres below the surface.",
  "scale": {
    "data": [
      { "sighting": "Survey ship hull", "m": 8, "icon": "ship" },
      { "sighting": "Kelp canopy", "m": 120, "icon": "leaf" },
      { "sighting": "Sardine shoal", "m": 310, "icon": "fish" },
      { "sighting": "Lanternfish layer", "m": 560, "icon": "fish" },
      { "sighting": "Swordfish", "m": 820, "icon": "fish" },
      { "sighting": "Coral mound", "m": 1150, "icon": "tree" },
      { "sighting": "Sperm whale", "m": 1480, "icon": "wave" },
      { "sighting": "Anglerfish", "m": 1900, "icon": "fish" },
      { "sighting": "Sensor array", "m": 2300, "icon": "satellite" },
      { "sighting": "Dumbo octopus", "m": 2750, "icon": "star" },
      { "sighting": "Sea cucumbers", "m": 3200, "icon": "circle" },
      { "sighting": "Seabed lander", "m": 3750, "icon": "pin" }
    ],
    "name": "sighting",
    "value": "m",
    "iconField": "icon",
    "direction": "down",
    "min": 0,
    "max": 4000,
    "format": "{value} m",
    "scaleLabel": "Depth, metres",
    "zones": [
      { "from": 0, "to": 200, "label": "Sunlit" },
      { "from": 200, "to": 1000, "label": "Twilight zone" },
      { "from": 1000, "to": 4000, "label": "Dark zone" }
    ]
  },
  "figures": [
    { "at": 200, "value": "1%", "label": "of surface light is left" },
    { "at": 1000, "value": "4°C", "label": "water temperature" },
    { "at": 3000, "value": "376 atm", "label": "pressure at the lander, 3,750 m down" }
  ],
  "side": {
    "data": [
      { "zone": "species in the sunlit zone", "species": 148 },
      { "zone": "species in the twilight zone", "species": 61 },
      { "zone": "species in the dark zone", "species": 23 }
    ],
    "name": "zone",
    "value": "species",
    "title": "Species logged",
    "height": 250
  },
  "sideAt": 1900,
  "sources": "Meridian Deep survey log",
  "note": "The Meridian Deep survey is invented. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `scale` (required) | `ScaleLadderConfig \| Slot` |  | The scale. A compact `scale-ladder` config: `{ data, name, value, iconField?, icon?, direction?, scale?, min?, max?, ticks?, zones?, scaleLabel?, format?, highlight? }`. Or a full spec, which replaces the ladder. |
| `figures` | `{ at: number; value: string; label: string; context?: string; icon?: string }[]` |  | Large figures for the side column. `at` is the position on the scale the figure belongs to; beside the scale the figure is set level with it under a dotted rule. |
| `side` | `StatCirclesConfig \| Slot` |  | One small graphic in the side column. A compact `stat-circles` config: `{ data, name, value, unit?, format?, title?, subtitle? }`. Or a full spec. |
| `sideAt` | `number` |  | Position on the scale where the `side` graphic starts. Default: under the last figure. |
| `height` | `number` |  | Height of the scale in px. Default: 68px per item, at least 920 (760 when stacked). |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"ocean"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `980` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [scale-ladder](https://insightcharts.dev/llms/scale-ladder.md), [stat-circles](https://insightcharts.dev/llms/stat-circles.md)
- Used by: no molecule or template yet

### More examples

#### Forest, a climb read upwards, linked

```tsx
import { ScalePoster } from "insightcharts";

<ScalePoster
  theme="forest"
  linked
  kicker="Mountains"
  title="The Mount Aldra trail climbs from 1,240 m to 5,320 m"
  subtitle="Altitude of nine points on the main trail, metres above sea level."
  scale={{
    data: [
      { place: "Trailhead village", m: 1240, icon: "house" },
      { place: "Cedar forest hut", m: 1820, icon: "tree" },
      { place: "Last farm terrace", m: 2150, icon: "wheat" },
      { place: "Treeline", m: 2900, icon: "leaf" },
      { place: "Meadow camp", m: 3350, icon: "flag" },
      { place: "Glacier lake", m: 3800, icon: "drop" },
      { place: "High camp", m: 4400, icon: "flag" },
      { place: "Snow line", m: 4750, icon: "snow" },
      { place: "Aldra summit", m: 5320, icon: "mountain" },
    ],
    name: "place",
    value: "m",
    iconField: "icon",
    min: 1000,
    max: 5500,
    format: "{value} m",
    scaleLabel: "Altitude, metres",
    highlight: "Aldra summit",
    zones: [
      { from: 1000, to: 2900, label: "Forest" },
      { from: 2900, to: 4750, label: "Meadow and rock" },
      { from: 4750, to: 5500, label: "Snow and ice" },
    ],
  }}
  figures={[
    { at: 5320, value: "53%", label: "of sea-level oxygen at the summit" },
    { at: 4400, value: "−9°C", label: "mean July temperature at the snow line, 4,750 m" },
    { at: 2900, value: "4,080 m", label: "of climbing from the trailhead to the summit" },
  ]}
  side={{
    data: [
      { leg: "Meadow camp", hours: 9 },
      { leg: "High camp", hours: 6 },
      { leg: "Aldra summit", hours: 5 },
    ],
    name: "leg",
    value: "hours",
    title: "Hours of walking to reach",
    height: 240,
    colorBy: "single",
  }}
  sideAt={3350}
  sources="Aldra National Park trail guide"
  note="Mount Aldra is an invented mountain. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Noir, a log scale, with download

```tsx
import { ScalePoster } from "insightcharts";

<ScalePoster
  theme="noir"
  download
  kicker="Space"
  title="The Moon is 384,400 km from Earth"
  subtitle="Height above Earth's surface of eight objects, kilometres, on a log scale."
  scale={{
    data: [
      { object: "Airliner at cruise", km: 11, icon: "plane" },
      { object: "Weather balloon", km: 35, icon: "circle" },
      { object: "Kármán line", km: 100, icon: "flag" },
      { object: "Space Station", km: 400, icon: "satellite" },
      { object: "Hubble telescope", km: 540, icon: "satellite" },
      { object: "GPS satellites", km: 20200, icon: "satellite" },
      { object: "Geostationary orbit", km: 35786, icon: "satellite" },
      { object: "The Moon", km: 384400, icon: "globe" },
    ],
    name: "object",
    value: "km",
    iconField: "icon",
    scale: "log",
    min: 10,
    max: 1000000,
    format: "{value} km",
    scaleLabel: "Height, km",
    zones: [
      { from: 10, to: 100, label: "Atmosphere" },
      { from: 100, to: 2000, label: "Low Earth orbit" },
      { from: 2000, to: 1000000, label: "High orbits and beyond" },
    ],
  }}
  figures={[
    { at: 384400, value: "3 days", label: "flight time of a crewed mission to the Moon" },
    { at: 35786, value: "24 hours", label: "to circle Earth once in geostationary orbit" },
    { at: 400, value: "92 min", label: "to circle Earth once on the space station" },
    { at: 100, value: "100 km", label: "is the usual line for the start of space" },
  ]}
  sources="NASA fact sheets"
  note="Rounded figures. Flight and orbit times are approximate."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/scale-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/scale-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Scorecard (`scorecard`)

> A recurring report. It has a masthead with the report name and period, a headline that states the main change, a KPI grid with changes and sparklines, a ranked list beside one or two trend charts, an optional comparison table, short notes and a source note.

- Component: `Scorecard` (import from `insightcharts`)
- Spec type: `"scorecard"`
- Level: template. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for weekly or monthly numbers. Keep the layout the same in every edition so readers know where each number is. Change the headline each edition to state the main change with its number. The headline and the KPI row should be enough for a reader who stops there. The ranking, trends and notes add detail. Highlight the one row or series the headline is about and leave the rest grey.

### Avoid

A one-off finding (use `executive-brief`). Readers who need to filter the data themselves (use `data-explorer`). More than six KPIs.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/scorecard
```

The file lands at `components/insightcharts/templates/scorecard.tsx`. `@insightcharts/scorecard-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, LineChart, Scorecard } from "insightcharts";

<Scorecard
  kicker="Online store scorecard"
  reportPeriod="October 2024"
  title="Orders rose 12% in October to 24,900"
  deck="The return rate was 11.4%. It was 8.4% in July, the month before free returns launched. Outerwear had the highest return rate at 19.2%."
  kpis={{
    data: [
      { month: "2023-11-01", orders: 18200, conversion: 2.61, aov: 64.1, returns: 8.1 },
      { month: "2023-12-01", orders: 26900, conversion: 3.02, aov: 66.8, returns: 8.4 },
      { month: "2024-01-01", orders: 17100, conversion: 2.55, aov: 63, returns: 9 },
      { month: "2024-02-01", orders: 16400, conversion: 2.58, aov: 62.4, returns: 8.2 },
      { month: "2024-03-01", orders: 17900, conversion: 2.66, aov: 62.9, returns: 8 },
      { month: "2024-04-01", orders: 18800, conversion: 2.71, aov: 62.2, returns: 7.9 },
      { month: "2024-05-01", orders: 19600, conversion: 2.74, aov: 61.8, returns: 8.3 },
      { month: "2024-06-01", orders: 19900, conversion: 2.78, aov: 61.5, returns: 8.1 },
      { month: "2024-07-01", orders: 20400, conversion: 2.83, aov: 61.9, returns: 8.4 },
      { month: "2024-08-01", orders: 21300, conversion: 2.9, aov: 61.2, returns: 9.6 },
      { month: "2024-09-01", orders: 22200, conversion: 2.97, aov: 60.8, returns: 10.5 },
      { month: "2024-10-01", orders: 24900, conversion: 3.1, aov: 61, returns: 11.4 },
    ],
    x: "month",
    compare: "previous",
    metrics: [
      { y: "orders", label: "Orders", format: "compact", deltaLabel: "vs September" },
      {
        y: "conversion",
        label: "Conversion rate",
        format: "{value}%",
        delta: "+0.13 pts",
        deltaLabel: "vs September",
      },
      { y: "aov", label: "Average order value", format: "currency:EUR", deltaLabel: "vs September" },
      {
        y: "returns",
        label: "Return rate",
        format: "{value}%",
        delta: "+0.9 pts",
        upIsGood: false,
        deltaLabel: "vs September",
      },
    ],
  }}
  ranking={{
    data: [
      { category: "Outerwear", revenue: 412, change: 0.31, returns: 19.2 },
      { category: "Footwear", revenue: 371, change: 0.08, returns: 14.1 },
      { category: "Knitwear", revenue: 298, change: 0.22, returns: 9.8 },
      { category: "Accessories", revenue: 164, change: -0.04, returns: 4.2 },
      { category: "Denim", revenue: 152, change: -0.11, returns: 12.6 },
      { category: "Home", revenue: 88, change: 0.02, returns: 3.1 },
    ],
    name: "category",
    value: "revenue",
    change: "change",
    format: "€{value}k",
    highlight: "Outerwear",
    title: "Outerwear revenue rose 31% to €412k in October",
    subtitle: "Revenue by category, October, with change on September",
  }}
  trends={[
    <LineChart
      data={[
        { month: "2023-11-01", orders: 18200, conversion: 2.61, aov: 64.1, returns: 8.1 },
        { month: "2023-12-01", orders: 26900, conversion: 3.02, aov: 66.8, returns: 8.4 },
        { month: "2024-01-01", orders: 17100, conversion: 2.55, aov: 63, returns: 9 },
        { month: "2024-02-01", orders: 16400, conversion: 2.58, aov: 62.4, returns: 8.2 },
        { month: "2024-03-01", orders: 17900, conversion: 2.66, aov: 62.9, returns: 8 },
        { month: "2024-04-01", orders: 18800, conversion: 2.71, aov: 62.2, returns: 7.9 },
        { month: "2024-05-01", orders: 19600, conversion: 2.74, aov: 61.8, returns: 8.3 },
        { month: "2024-06-01", orders: 19900, conversion: 2.78, aov: 61.5, returns: 8.1 },
        { month: "2024-07-01", orders: 20400, conversion: 2.83, aov: 61.9, returns: 8.4 },
        { month: "2024-08-01", orders: 21300, conversion: 2.9, aov: 61.2, returns: 9.6 },
        { month: "2024-09-01", orders: 22200, conversion: 2.97, aov: 60.8, returns: 10.5 },
        { month: "2024-10-01", orders: 24900, conversion: 3.1, aov: 61, returns: 11.4 },
      ]}
      x="month"
      y="returns"
      format="{value}%"
      zero
      title="The return rate rose from 8.4% in July to 11.4% in October"
      subtitle="Share of orders returned, by month of order"
      annotations={[{ type: "line", axis: "x", value: "2024-08-01", label: "Free returns" }]}
    />,
    <BarChart
      data={[
        { category: "Outerwear", revenue: 412, change: 0.31, returns: 19.2 },
        { category: "Footwear", revenue: 371, change: 0.08, returns: 14.1 },
        { category: "Knitwear", revenue: 298, change: 0.22, returns: 9.8 },
        { category: "Accessories", revenue: 164, change: -0.04, returns: 4.2 },
        { category: "Denim", revenue: 152, change: -0.11, returns: 12.6 },
        { category: "Home", revenue: 88, change: 0.02, returns: 3.1 },
      ]}
      x="category"
      y="returns"
      sort="desc"
      orientation="horizontal"
      format="{value}%"
      highlight="Outerwear"
      title="19.2% of outerwear orders were returned in October"
      subtitle="Return rate by category, October"
    />,
  ]}
  notes={[
    {
      title: "Returns cost about €62k in October",
      text: "About 2,840 parcels came back. Carriage and handling cost €22 a parcel. At September's return rate of 10.5% the cost would have been about €58k.",
    },
    {
      title: "62% of outerwear returns give “too small” as the reason",
      text: "A size guide goes into test on 4 November.",
    },
    {
      title: "Orders were highest in December 2023 at 26,900",
      text: "October 2024 was the second-highest month of the 12.",
    },
  ]}
  sources={["Store order database", "Returns portal"]}
  period="November 2023 to October 2024"
  method="Return rate is by month of order and is revised for 30 days as parcels arrive."
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "scorecard",
  "kicker": "Online store scorecard",
  "reportPeriod": "October 2024",
  "title": "Orders rose 12% in October to 24,900",
  "deck": "The return rate was 11.4%. It was 8.4% in July, the month before free returns launched. Outerwear had the highest return rate at 19.2%.",
  "kpis": {
    "data": [
      { "month": "2023-11-01", "orders": 18200, "conversion": 2.61, "aov": 64.1, "returns": 8.1 },
      { "month": "2023-12-01", "orders": 26900, "conversion": 3.02, "aov": 66.8, "returns": 8.4 },
      { "month": "2024-01-01", "orders": 17100, "conversion": 2.55, "aov": 63, "returns": 9 },
      { "month": "2024-02-01", "orders": 16400, "conversion": 2.58, "aov": 62.4, "returns": 8.2 },
      { "month": "2024-03-01", "orders": 17900, "conversion": 2.66, "aov": 62.9, "returns": 8 },
      { "month": "2024-04-01", "orders": 18800, "conversion": 2.71, "aov": 62.2, "returns": 7.9 },
      { "month": "2024-05-01", "orders": 19600, "conversion": 2.74, "aov": 61.8, "returns": 8.3 },
      { "month": "2024-06-01", "orders": 19900, "conversion": 2.78, "aov": 61.5, "returns": 8.1 },
      { "month": "2024-07-01", "orders": 20400, "conversion": 2.83, "aov": 61.9, "returns": 8.4 },
      { "month": "2024-08-01", "orders": 21300, "conversion": 2.9, "aov": 61.2, "returns": 9.6 },
      { "month": "2024-09-01", "orders": 22200, "conversion": 2.97, "aov": 60.8, "returns": 10.5 },
      { "month": "2024-10-01", "orders": 24900, "conversion": 3.1, "aov": 61, "returns": 11.4 }
    ],
    "x": "month",
    "compare": "previous",
    "metrics": [
      { "y": "orders", "label": "Orders", "format": "compact", "deltaLabel": "vs September" },
      {
        "y": "conversion",
        "label": "Conversion rate",
        "format": "{value}%",
        "delta": "+0.13 pts",
        "deltaLabel": "vs September"
      },
      {
        "y": "aov",
        "label": "Average order value",
        "format": "currency:EUR",
        "deltaLabel": "vs September"
      },
      {
        "y": "returns",
        "label": "Return rate",
        "format": "{value}%",
        "delta": "+0.9 pts",
        "upIsGood": false,
        "deltaLabel": "vs September"
      }
    ]
  },
  "ranking": {
    "data": [
      { "category": "Outerwear", "revenue": 412, "change": 0.31, "returns": 19.2 },
      { "category": "Footwear", "revenue": 371, "change": 0.08, "returns": 14.1 },
      { "category": "Knitwear", "revenue": 298, "change": 0.22, "returns": 9.8 },
      { "category": "Accessories", "revenue": 164, "change": -0.04, "returns": 4.2 },
      { "category": "Denim", "revenue": 152, "change": -0.11, "returns": 12.6 },
      { "category": "Home", "revenue": 88, "change": 0.02, "returns": 3.1 }
    ],
    "name": "category",
    "value": "revenue",
    "change": "change",
    "format": "€{value}k",
    "highlight": "Outerwear",
    "title": "Outerwear revenue rose 31% to €412k in October",
    "subtitle": "Revenue by category, October, with change on September"
  },
  "trends": [
    {
      "type": "line-chart",
      "data": [
        { "month": "2023-11-01", "orders": 18200, "conversion": 2.61, "aov": 64.1, "returns": 8.1 },
        { "month": "2023-12-01", "orders": 26900, "conversion": 3.02, "aov": 66.8, "returns": 8.4 },
        { "month": "2024-01-01", "orders": 17100, "conversion": 2.55, "aov": 63, "returns": 9 },
        { "month": "2024-02-01", "orders": 16400, "conversion": 2.58, "aov": 62.4, "returns": 8.2 },
        { "month": "2024-03-01", "orders": 17900, "conversion": 2.66, "aov": 62.9, "returns": 8 },
        { "month": "2024-04-01", "orders": 18800, "conversion": 2.71, "aov": 62.2, "returns": 7.9 },
        { "month": "2024-05-01", "orders": 19600, "conversion": 2.74, "aov": 61.8, "returns": 8.3 },
        { "month": "2024-06-01", "orders": 19900, "conversion": 2.78, "aov": 61.5, "returns": 8.1 },
        { "month": "2024-07-01", "orders": 20400, "conversion": 2.83, "aov": 61.9, "returns": 8.4 },
        { "month": "2024-08-01", "orders": 21300, "conversion": 2.9, "aov": 61.2, "returns": 9.6 },
        { "month": "2024-09-01", "orders": 22200, "conversion": 2.97, "aov": 60.8, "returns": 10.5 },
        { "month": "2024-10-01", "orders": 24900, "conversion": 3.1, "aov": 61, "returns": 11.4 }
      ],
      "x": "month",
      "y": "returns",
      "format": "{value}%",
      "zero": true,
      "title": "The return rate rose from 8.4% in July to 11.4% in October",
      "subtitle": "Share of orders returned, by month of order",
      "annotations": [{ "type": "line", "axis": "x", "value": "2024-08-01", "label": "Free returns" }]
    },
    {
      "type": "bar-chart",
      "data": [
        { "category": "Outerwear", "revenue": 412, "change": 0.31, "returns": 19.2 },
        { "category": "Footwear", "revenue": 371, "change": 0.08, "returns": 14.1 },
        { "category": "Knitwear", "revenue": 298, "change": 0.22, "returns": 9.8 },
        { "category": "Accessories", "revenue": 164, "change": -0.04, "returns": 4.2 },
        { "category": "Denim", "revenue": 152, "change": -0.11, "returns": 12.6 },
        { "category": "Home", "revenue": 88, "change": 0.02, "returns": 3.1 }
      ],
      "x": "category",
      "y": "returns",
      "sort": "desc",
      "orientation": "horizontal",
      "format": "{value}%",
      "highlight": "Outerwear",
      "title": "19.2% of outerwear orders were returned in October",
      "subtitle": "Return rate by category, October"
    }
  ],
  "notes": [
    {
      "title": "Returns cost about €62k in October",
      "text": "About 2,840 parcels came back. Carriage and handling cost €22 a parcel. At September's return rate of 10.5% the cost would have been about €58k."
    },
    {
      "title": "62% of outerwear returns give “too small” as the reason",
      "text": "A size guide goes into test on 4 November."
    },
    {
      "title": "Orders were highest in December 2023 at 26,900",
      "text": "October 2024 was the second-highest month of the 12."
    }
  ],
  "sources": ["Store order database", "Returns portal"],
  "period": "November 2023 to October 2024",
  "method": "Return rate is by month of order and is revised for 30 days as parcels arrive.",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The main change this period, as one plain sentence with the number in it. |
| `kicker` | `string` |  | The name of the report, e.g. "Store scorecard". Shown in the masthead. |
| `reportPeriod` | `string` |  | The period reported, e.g. "October 2024". Shown opposite the report name. |
| `deck` | `string` |  | One-sentence standfirst. |
| `byline` | `string` |  | Author line. |
| `date` | `string` |  | Publication date. |
| `kpis` | `{ data, x, metrics, compare?, change?, columns? }` |  | The headline metrics: the props of `kpi-grid`. One time-ordered dataset, one card per metric. |
| `ranking` | `{ data, name, value, change?, highlight?, title?, ... } \| Slot` |  | A ranking: the props of `ranked-list`, or any spec or element. |
| `trends` | `Slot[]` |  | One or two trend exhibits, shown beside the ranking in wide containers. |
| `table` | `{ data, columns, highlight?, sort?, title?, ... } \| Slot` |  | A comparison across entities: the props of `comparison-table`, or any spec or element. |
| `notes` | `(string \| { title, text? })[]` |  | Short notes on what changed in the period. Each states one fact with its number. |
| `notesTitle` | `string` | `"Notes"` | Heading of the notes. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `maxWidth` | `number \| string` |  | Widest the piece may get. It is centred in wider containers. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [kpi-grid](https://insightcharts.dev/llms/kpi-grid.md), [ranked-list](https://insightcharts.dev/llms/ranked-list.md), [comparison-table](https://insightcharts.dev/llms/comparison-table.md), [prose](https://insightcharts.dev/llms/prose.md), [source-note](https://insightcharts.dev/llms/source-note.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md)
- Used by: no molecule or template yet

### More examples

#### Sport: a table instead of a ranking

```tsx
import { LineChart, Scorecard } from "insightcharts";

<Scorecard
  kicker="Harbour City FC · first-team report"
  reportPeriod="After 19 of 38 matches"
  title="Harbour City are second with 36 points after 19 matches"
  deck="That is 10 points more than at the same stage last season. Goals conceded fell from 1.67 a match in August to 0.60 in December."
  kpis={{
    data: [
      { month: "August", ppg: 1.33, gf: 1, ga: 1.67, xgd: -0.21 },
      { month: "September", ppg: 1.5, gf: 1.25, ga: 1.25, xgd: 0.05 },
      { month: "October", ppg: 2, gf: 1.75, ga: 1, xgd: 0.42 },
      { month: "November", ppg: 2.25, gf: 2, ga: 0.75, xgd: 0.71 },
      { month: "December", ppg: 2.4, gf: 2.2, ga: 0.6, xgd: 0.88 },
    ],
    x: "month",
    compare: "first",
    change: "absolute",
    columns: 4,
    metrics: [
      { y: "ppg", label: "Points per match", format: "decimal:2", deltaLabel: "vs August" },
      { y: "gf", label: "Goals scored per match", format: "decimal:2", deltaLabel: "vs August" },
      {
        y: "ga",
        label: "Goals conceded per match",
        format: "decimal:2",
        upIsGood: false,
        deltaLabel: "vs August",
      },
      {
        y: "xgd",
        label: "Expected goal difference per match",
        format: { signDisplay: "exceptZero", maximumFractionDigits: 2 },
        deltaLabel: "vs August",
      },
    ],
  }}
  trends={[
    <LineChart
      data={[
        { match: "1", "2024/25": 0, "2023/24": 1 },
        { match: "2", "2024/25": 1, "2023/24": 4 },
        { match: "3", "2024/25": 1, "2023/24": 4 },
        { match: "4", "2024/25": 4, "2023/24": 5 },
        { match: "5", "2024/25": 5, "2023/24": 6 },
        { match: "6", "2024/25": 8, "2023/24": 9 },
        { match: "7", "2024/25": 9, "2023/24": 9 },
        { match: "8", "2024/25": 12, "2023/24": 10 },
        { match: "9", "2024/25": 13, "2023/24": 13 },
        { match: "10", "2024/25": 16, "2023/24": 14 },
        { match: "11", "2024/25": 19, "2023/24": 14 },
        { match: "12", "2024/25": 20, "2023/24": 17 },
        { match: "13", "2024/25": 23, "2023/24": 18 },
        { match: "14", "2024/25": 26, "2023/24": 18 },
        { match: "15", "2024/25": 27, "2023/24": 21 },
        { match: "16", "2024/25": 30, "2023/24": 22 },
        { match: "17", "2024/25": 33, "2023/24": 22 },
        { match: "18", "2024/25": 33, "2023/24": 25 },
        { match: "19", "2024/25": 36, "2023/24": 26 },
      ]}
      x="match"
      y={["2024/25", "2023/24"]}
      highlight="2024/25"
      zero
      height={280}
      title="Harbour City have 36 points after 19 matches, against 26 last season"
      subtitle="Cumulative league points by match played"
      annotations={[{ type: "line", axis: "x", value: "8", label: "Back three introduced" }]}
    />,
  ]}
  table={{
    data: [
      { team: "Northfield", played: 19, gd: 21, points: 41, f1: 3, f2: 3, f3: 1, f4: 3, f5: 0 },
      { team: "Harbour City", played: 19, gd: 14, points: 36, f1: 3, f2: 3, f3: 3, f4: 1, f5: 3 },
      { team: "Easton Vale", played: 19, gd: 12, points: 35, f1: 1, f2: 0, f3: 3, f4: 1, f5: 1 },
      { team: "Calder Rovers", played: 19, gd: 9, points: 33, f1: 0, f2: 3, f3: 1, f4: 0, f5: 3 },
      { team: "Westmoor", played: 19, gd: 3, points: 31, f1: 3, f2: 1, f3: 0, f4: 1, f5: 1 },
      { team: "St Olave's", played: 19, gd: 1, points: 29, f1: 1, f2: 1, f3: 0, f4: 3, f5: 0 },
    ],
    title: "Harbour City are 5 points behind Northfield",
    subtitle: "League table, top six, with points from each of the last five matches",
    highlight: "Harbour City",
    columns: [
      { key: "team", label: "Team" },
      { key: "played", label: "Played", hideBelow: 520 },
      { key: "gd", label: "Goal difference", format: "signed", hideBelow: 420 },
      {
        key: "form",
        label: "Last five",
        kind: "sparkline",
        mark: "bar",
        fields: ["f1", "f2", "f3", "f4", "f5"],
      },
      { key: "points", label: "Points", kind: "bar", format: "integer" },
    ],
  }}
  notes={[
    "Harbour City took 13 points from the last five matches. Northfield took 10.",
    "Expected goal difference rose from −0.21 a match in August to +0.88 in December.",
  ]}
  sources="Club performance analysis"
  note="Illustrative data. The clubs are fictional."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/scorecard.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/scorecard.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Social card (`social-card`)

> A 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.

- Component: `SocialCard` (import from `insightcharts`)
- Spec type: `"social-card"`
- Level: template. Category: layout.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for one finding that will be shared in a feed, a slide or a chat thread with no text around it. State the fact with its number in the headline. Use one simple exhibit, such as one highlighted bar, one line or one number. Put the source and your name on the card, because it will be shared without the page. Use 1:1 or 4:5 for feeds, 16:9 for slides and link previews, 9:16 for stories.

### Avoid

More than one fact or more than one exhibit (use `story-deck` for a sequence, `executive-brief` for a page). Charts that need a legend, small labels or hovering to read, because a shared image is not interactive. An exhibit with its own `title`, because the card's headline is the title.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/social-card
```

The file lands at `components/insightcharts/templates/social-card.tsx`. `@insightcharts/social-card-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, SocialCard } from "insightcharts";

<SocialCard
  aspect="1:1"
  kicker="Climate"
  title="The world was 1.6°C warmer in 2024 than in 1850 to 1900"
  exhibit={<BarChart
    data={[
      { year: "2015", c: 1.17 },
      { year: "2016", c: 1.31 },
      { year: "2017", c: 1.22 },
      { year: "2018", c: 1.14 },
      { year: "2019", c: 1.26 },
      { year: "2020", c: 1.31 },
      { year: "2021", c: 1.14 },
      { year: "2022", c: 1.18 },
      { year: "2023", c: 1.48 },
      { year: "2024", c: 1.6 },
    ]}
    x="year"
    y="c"
    orientation="vertical"
    sort="none"
    highlight="2024"
    format="{value}°C"
    labels={false}
    subtitle="Global average temperature above the 1850 to 1900 level"
    annotations={[{ type: "line", axis: "y", value: 1.5, label: "Paris Agreement limit" }]}
  />}
  source="Copernicus Climate Change Service, ERA5 (rounded)"
  note="Figures are approximate, for illustration"
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "social-card",
  "aspect": "1:1",
  "kicker": "Climate",
  "title": "The world was 1.6°C warmer in 2024 than in 1850 to 1900",
  "exhibit": {
    "type": "bar-chart",
    "data": [
      { "year": "2015", "c": 1.17 },
      { "year": "2016", "c": 1.31 },
      { "year": "2017", "c": 1.22 },
      { "year": "2018", "c": 1.14 },
      { "year": "2019", "c": 1.26 },
      { "year": "2020", "c": 1.31 },
      { "year": "2021", "c": 1.14 },
      { "year": "2022", "c": 1.18 },
      { "year": "2023", "c": 1.48 },
      { "year": "2024", "c": 1.6 }
    ],
    "x": "year",
    "y": "c",
    "orientation": "vertical",
    "sort": "none",
    "highlight": "2024",
    "format": "{value}°C",
    "labels": false,
    "subtitle": "Global average temperature above the 1850 to 1900 level",
    "annotations": [{ "type": "line", "axis": "y", "value": 1.5, "label": "Paris Agreement limit" }]
  },
  "source": "Copernicus Climate Change Service, ERA5 (rounded)",
  "note": "Figures are approximate, for illustration",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The card's one fact, as a plain sentence with the number in it. |
| `kicker` | `string` |  | Small label above the title. |
| `deck` | `string` |  | One short line under the title: the measure, or the number in words. |
| `exhibit` | `Slot` |  | The one exhibit. A chart spec is given the height left in the card (any `height` you set wins); leave out its `title`. |
| `source` | `string` |  | Where the data comes from, shown as "Source: ...". |
| `note` | `string` |  | Caveat shown after the source, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made it: a name, handle or publication. |
| `aspect` | `"1:1" \| "4:5" \| "16:9" \| "9:16"` | `"1:1"` | Shape of the card. |
| `tone` | `"surface" \| "inverse"` | `"surface"` | `inverse` paints the card in the opposite colour mode. |
| `downloadable` | `boolean` | `true` | Show the download button under the card. The image is the whole card, drawn from the DOM onto a canvas. |
| `exportWidth` | `number` | `1080` | Width of the downloaded PNG in pixels (1920 for 16:9). |
| `filename` | `string` |  | File name without extension. Defaults to a slug of the title. |
| `downloadLabel` | `string` | `"Download PNG"` | Label of the download button. |
| `maxWidth` | `number` |  | Widest the card is drawn on screen, in px. Default 540 (520 for 4:5, 720 for 16:9, 400 for 9:16). In narrower containers the whole card is scaled down, like an image, so its composition never changes. |
| `onExport` | `(blob: Blob) => void` |  | Called with the PNG after a download. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading level of the title. |
| `theme` | `ThemeInput` |  | Theme override, passed on to the exhibit. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode. |

### Composition

- Composes: [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [big-number](https://insightcharts.dev/llms/big-number.md), [waffle-chart](https://insightcharts.dev/llms/waffle-chart.md), [source-note](https://insightcharts.dev/llms/source-note.md)
- Used by: no molecule or template yet

### More examples

#### 16:9, public health, inverse tone

```tsx
import { BarChart, SocialCard } from "insightcharts";

<SocialCard
  aspect="16:9"
  tone="inverse"
  kicker="Public health"
  title="Reported measles cases in Europe rose from 61,000 in 2023 to 127,000 in 2024"
  exhibit={<BarChart
    data={[
      { year: "2019", cases: 106 },
      { year: "2020", cases: 12 },
      { year: "2021", cases: 0.2 },
      { year: "2022", cases: 0.9 },
      { year: "2023", cases: 61 },
      { year: "2024", cases: 127 },
    ]}
    x="year"
    y="cases"
    orientation="vertical"
    sort="none"
    highlight="2024"
    format="{value}k"
    subtitle="Reported measles cases, WHO European Region, thousands"
  />}
  source="WHO and UNICEF (rounded)"
  note="Figures are approximate, for illustration"
  credit="Data desk"
/>
```

#### 9:16, transport, a proportion instead of a chart

```tsx
import { SocialCard, WaffleChart } from "insightcharts";

<SocialCard
  aspect="9:16"
  kicker="Transport"
  title="58% of car journeys in England are under five miles"
  deck="Each square is 1% of car journeys."
  exhibit={<WaffleChart
    data={[{ group: "Under five miles", share: 58 }]}
    name="group"
    value="share"
    total={100}
    restLabel="Five miles or more"
    legend={false}
    aspect={1}
  />}
  source="National Travel Survey"
  note="Rounded, approximate figures for illustration"
  credit="@datadesk"
/>
```

#### 4:5, personal finance, a single number

```tsx
import { BigNumber, SocialCard } from "insightcharts";

<SocialCard
  aspect="4:5"
  kicker="Money"
  title="Starting to save at 35 instead of 25 leaves $296,000 less at 65"
  exhibit={<BigNumber
    size="hero"
    value="$296,000"
    label="Less at 65 if you start at 35 instead of 25"
    context="Saving $300 a month at a 6% real return"
  />}
  source="Author's calculation"
  note="Illustrative"
  credit="InsightCharts"
  downloadable={false}
/>
```

### Links

- Registry item: https://insightcharts.dev/r/social-card.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/social-card.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Story deck (`story-deck`)

> A sequence of full-frame cards (title, stat, chart, quote, closing) that the reader swipes or steps through. Each card states one fact. It has an optional fixed aspect ratio, a keyboard-accessible pager and a stacked layout for print.

- Component: `StoryDeck` (import from `insightcharts`)
- Spec type: `"story-deck"`
- Level: template. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for a short sequence read on a phone, such as a “year in review”. Each card should be readable in a couple of seconds. State the main fact with its number on the title card. Put one fact on each later card, as a number or as one chart with one highlighted mark under a headline that states the fact. Use five to ten cards. End with a closing card and the sources. Charts in cards should have few data points and direct labels, with no legend.

### Avoid

Findings that need two exhibits in view at once (use `executive-brief`). A single shareable image (use `social-card`). Dense charts or long paragraphs, because a card has little room. One chart that changes step by step (use `scrolly-chart` in `steps` mode).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/story-deck
```

The file lands at `components/insightcharts/templates/story-deck.tsx`. `@insightcharts/story-deck-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, LineChart, RadialBarChart, StoryDeck } from "insightcharts";

<StoryDeck
  aspect="4:5"
  cards={[
    {
      kind: "title",
      tone: "inverse",
      kicker: "Your 2024 on the road",
      title: "You ran 1,842 km in 2024",
      deck: "That was 23% more than in 2023. You ran 187 times.",
      byline: "Riverside Runners · member report",
    },
    {
      kind: "stat",
      kicker: "Distance",
      value: 1842,
      format: "integer",
      label: "Kilometres run in 2024",
      delta: 0.23,
      deltaLabel: "vs 2023",
      context: "An average of 154 km a month",
      text: "You ran in 46 of the year's 52 weeks.",
    },
    {
      kind: "chart",
      kicker: "Month by month",
      title: "October was your highest month at 224 km",
      chart: <BarChart
        data={[
          { month: "Jan", km: 96 },
          { month: "Feb", km: 104 },
          { month: "Mar", km: 131 },
          { month: "Apr", km: 148 },
          { month: "May", km: 162 },
          { month: "Jun", km: 171 },
          { month: "Jul", km: 120 },
          { month: "Aug", km: 158 },
          { month: "Sep", km: 196 },
          { month: "Oct", km: 224 },
          { month: "Nov", km: 181 },
          { month: "Dec", km: 151 },
        ]}
        x="month"
        y="km"
        orientation="vertical"
        sort="none"
        highlight="Oct"
        labels={false}
        format="{value} km"
        height={240}
      />,
      text: "You ran 120 km in July while you were injured. You ran 158 km in August.",
    },
    {
      kind: "chart",
      kicker: "Pace",
      title: "Your easy pace fell from 5.52 to 5.04 minutes per kilometre",
      chart: <LineChart
        data={[
          { month: "Jan", pace: 5.52 },
          { month: "Feb", pace: 5.47 },
          { month: "Mar", pace: 5.41 },
          { month: "Apr", pace: 5.36 },
          { month: "May", pace: 5.33 },
          { month: "Jun", pace: 5.28 },
          { month: "Jul", pace: 5.31 },
          { month: "Aug", pace: 5.24 },
          { month: "Sep", pace: 5.16 },
          { month: "Oct", pace: 5.09 },
          { month: "Nov", pace: 5.07 },
          { month: "Dec", pace: 5.04 },
        ]}
        x="month"
        y="pace"
        format="{value} min/km"
        height={240}
      />,
      text: "A lower number is a faster pace. Your pace in August was 5.24.",
    },
    {
      kind: "chart",
      kicker: "Habits",
      tone: "accent",
      title: "41 of your 187 runs started between 6am and 7am",
      chart: <RadialBarChart
        data={[
          { hour: "00", runs: 0 },
          { hour: "01", runs: 0 },
          { hour: "02", runs: 0 },
          { hour: "03", runs: 0 },
          { hour: "04", runs: 0 },
          { hour: "05", runs: 9 },
          { hour: "06", runs: 41 },
          { hour: "07", runs: 38 },
          { hour: "08", runs: 12 },
          { hour: "09", runs: 4 },
          { hour: "10", runs: 2 },
          { hour: "11", runs: 3 },
          { hour: "12", runs: 8 },
          { hour: "13", runs: 6 },
          { hour: "14", runs: 2 },
          { hour: "15", runs: 1 },
          { hour: "16", runs: 3 },
          { hour: "17", runs: 11 },
          { hour: "18", runs: 22 },
          { hour: "19", runs: 17 },
          { hour: "20", runs: 6 },
          { hour: "21", runs: 2 },
          { hour: "22", runs: 0 },
          { hour: "23", runs: 0 },
        ]}
        x="hour"
        y="runs"
        labelEvery={3}
        labels={false}
        height={260}
      />,
      text: "Another 38 started between 7am and 8am. 22 started between 6pm and 7pm.",
    },
    {
      kind: "quote",
      quote: "I started running before work in the spring. I have kept to it since.",
      attribution: "Club member",
      role: "Club newsletter, December 2024",
    },
    {
      kind: "closing",
      kicker: "Next year",
      title: "2,000 km in 2025 needs 167 km a month",
      text: "You averaged 154 km a month in 2024.",
      points: ["You ran 167 km or more in 4 months of 2024.", "July was 51 km below June."],
      action: { label: "Set a 2025 goal", href: "#goal" },
    },
  ]}
  sources="Club activity tracker"
  period="1 January to 31 December 2024"
  note="Illustrative data"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "story-deck",
  "aspect": "4:5",
  "cards": [
    {
      "kind": "title",
      "tone": "inverse",
      "kicker": "Your 2024 on the road",
      "title": "You ran 1,842 km in 2024",
      "deck": "That was 23% more than in 2023. You ran 187 times.",
      "byline": "Riverside Runners · member report"
    },
    {
      "kind": "stat",
      "kicker": "Distance",
      "value": 1842,
      "format": "integer",
      "label": "Kilometres run in 2024",
      "delta": 0.23,
      "deltaLabel": "vs 2023",
      "context": "An average of 154 km a month",
      "text": "You ran in 46 of the year's 52 weeks."
    },
    {
      "kind": "chart",
      "kicker": "Month by month",
      "title": "October was your highest month at 224 km",
      "chart": {
        "type": "bar-chart",
        "data": [
          { "month": "Jan", "km": 96 },
          { "month": "Feb", "km": 104 },
          { "month": "Mar", "km": 131 },
          { "month": "Apr", "km": 148 },
          { "month": "May", "km": 162 },
          { "month": "Jun", "km": 171 },
          { "month": "Jul", "km": 120 },
          { "month": "Aug", "km": 158 },
          { "month": "Sep", "km": 196 },
          { "month": "Oct", "km": 224 },
          { "month": "Nov", "km": 181 },
          { "month": "Dec", "km": 151 }
        ],
        "x": "month",
        "y": "km",
        "orientation": "vertical",
        "sort": "none",
        "highlight": "Oct",
        "labels": false,
        "format": "{value} km",
        "height": 240
      },
      "text": "You ran 120 km in July while you were injured. You ran 158 km in August."
    },
    {
      "kind": "chart",
      "kicker": "Pace",
      "title": "Your easy pace fell from 5.52 to 5.04 minutes per kilometre",
      "chart": {
        "type": "line-chart",
        "data": [
          { "month": "Jan", "pace": 5.52 },
          { "month": "Feb", "pace": 5.47 },
          { "month": "Mar", "pace": 5.41 },
          { "month": "Apr", "pace": 5.36 },
          { "month": "May", "pace": 5.33 },
          { "month": "Jun", "pace": 5.28 },
          { "month": "Jul", "pace": 5.31 },
          { "month": "Aug", "pace": 5.24 },
          { "month": "Sep", "pace": 5.16 },
          { "month": "Oct", "pace": 5.09 },
          { "month": "Nov", "pace": 5.07 },
          { "month": "Dec", "pace": 5.04 }
        ],
        "x": "month",
        "y": "pace",
        "format": "{value} min/km",
        "height": 240
      },
      "text": "A lower number is a faster pace. Your pace in August was 5.24."
    },
    {
      "kind": "chart",
      "kicker": "Habits",
      "tone": "accent",
      "title": "41 of your 187 runs started between 6am and 7am",
      "chart": {
        "type": "radial-bar-chart",
        "data": [
          { "hour": "00", "runs": 0 },
          { "hour": "01", "runs": 0 },
          { "hour": "02", "runs": 0 },
          { "hour": "03", "runs": 0 },
          { "hour": "04", "runs": 0 },
          { "hour": "05", "runs": 9 },
          { "hour": "06", "runs": 41 },
          { "hour": "07", "runs": 38 },
          { "hour": "08", "runs": 12 },
          { "hour": "09", "runs": 4 },
          { "hour": "10", "runs": 2 },
          { "hour": "11", "runs": 3 },
          { "hour": "12", "runs": 8 },
          { "hour": "13", "runs": 6 },
          { "hour": "14", "runs": 2 },
          { "hour": "15", "runs": 1 },
          { "hour": "16", "runs": 3 },
          { "hour": "17", "runs": 11 },
          { "hour": "18", "runs": 22 },
          { "hour": "19", "runs": 17 },
          { "hour": "20", "runs": 6 },
          { "hour": "21", "runs": 2 },
          { "hour": "22", "runs": 0 },
          { "hour": "23", "runs": 0 }
        ],
        "x": "hour",
        "y": "runs",
        "labelEvery": 3,
        "labels": false,
        "height": 260
      },
      "text": "Another 38 started between 7am and 8am. 22 started between 6pm and 7pm."
    },
    {
      "kind": "quote",
      "quote": "I started running before work in the spring. I have kept to it since.",
      "attribution": "Club member",
      "role": "Club newsletter, December 2024"
    },
    {
      "kind": "closing",
      "kicker": "Next year",
      "title": "2,000 km in 2025 needs 167 km a month",
      "text": "You averaged 154 km a month in 2024.",
      "points": ["You ran 167 km or more in 4 months of 2024.", "July was 51 km below June."],
      "action": { "label": "Set a 2025 goal", "href": "#goal" }
    }
  ],
  "sources": "Club activity tracker",
  "period": "1 January to 31 December 2024",
  "note": "Illustrative data"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `cards` (required) | `Card[]` |  | The cards in order. Each has a `kind`: `title` `{ title, deck?, byline? }`; `stat` `{ value, label, context?, delta?, deltaLabel?, upIsGood?, format?, text? }`; `chart` `{ title, chart, text? }`; `quote` `{ quote, attribution?, role? }`; `closing` `{ title, text?, points?, action?: { label, href } }`. Any card takes `kicker`, `tone: "surface" \| "inverse" \| "accent"` and `id`. |
| `label` | `string` |  | Accessible name of the deck. Defaults to the first card's title. |
| `aspect` | `"auto" \| "9:16" \| "4:5" \| "1:1" \| "16:9"` | `"4:5"` | Shape of every card. `auto` lets cards take the height their content needs. `16:9` falls back to `4:5` in containers under 520px. |
| `layout` | `"pager" \| "stack"` | `"pager"` | `pager` shows one card at a time (swipe, buttons, dots, arrow keys, Home/End). `stack` lists every card in a column. |
| `startAt` | `number` | `0` | Card shown first (zero-based). |
| `onCardChange` | `(index: number) => void` |  | Called when the visible card changes. |
| `maxWidth` | `number` |  | Widest a card is drawn, in px. Default 440 (400 for 9:16, 520 for 1:1, 840 for 16:9). Type and spacing scale with the card. |
| `previousLabel` | `string` | `"Previous"` | Label of the previous button. |
| `nextLabel` | `string` | `"Next"` | Label of the next button. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [big-number](https://insightcharts.dev/llms/big-number.md), [prose](https://insightcharts.dev/llms/prose.md), [pull-quote](https://insightcharts.dev/llms/pull-quote.md), [source-note](https://insightcharts.dev/llms/source-note.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [radial-bar-chart](https://insightcharts.dev/llms/radial-bar-chart.md)
- Used by: no molecule or template yet

### More examples

#### Education: landscape cards

```tsx
import { BarChart, LineChart, StoryDeck } from "insightcharts";

<StoryDeck
  aspect="16:9"
  cards={[
    {
      kind: "title",
      kicker: "City libraries · 2024 in review",
      title: "Digital loans were higher than print loans in 2024 for the first time",
      deck: "The five branches had 908,000 visits. That is 91% of the 2019 total.",
    },
    {
      kind: "chart",
      kicker: "Lending",
      title: "Digital loans were 1.33 million in 2024 against 1.24 million for print",
      chart: <LineChart
        data={[
          { year: "2020", Print: 1.42, Digital: 0.61 },
          { year: "2021", Print: 1.18, Digital: 0.83 },
          { year: "2022", Print: 1.31, Digital: 0.92 },
          { year: "2023", Print: 1.29, Digital: 1.08 },
          { year: "2024", Print: 1.24, Digital: 1.33 },
        ]}
        x="year"
        y={["Digital", "Print"]}
        highlight="Digital"
        format="{value}m"
        zero
        height={220}
      />,
    },
    {
      kind: "stat",
      kicker: "Visits",
      value: 908000,
      format: "compact",
      label: "Visits to the five branches",
      delta: 0.07,
      deltaLabel: "vs 2023",
      context: "91% of the 2019 total",
    },
    {
      kind: "chart",
      kicker: "Branches",
      title: "Central had 412,000 of the 908,000 visits",
      chart: <BarChart
        data={[
          { branch: "Central", visits: 412 },
          { branch: "Eastgate", visits: 188 },
          { branch: "Millbrook", visits: 141 },
          { branch: "Harbour", visits: 96 },
          { branch: "Hillside", visits: 71 },
        ]}
        x="branch"
        y="visits"
        orientation="horizontal"
        sort="none"
        highlight="Central"
        format="{value}k"
      />,
    },
    {
      kind: "closing",
      tone: "inverse",
      title: "Eastgate will open for longer hours in 2025",
      text: "The e-book budget will also increase.",
      action: { label: "Read the annual report", href: "#report" },
    },
  ]}
  sources="City library service annual return"
  note="Illustrative data"
/>
```

#### Stacked, auto height

```tsx
import { StoryDeck } from "insightcharts";

<StoryDeck
  layout="stack"
  aspect="auto"
  cards={[
    {
      kind: "stat",
      kicker: "Distance",
      value: 1842,
      format: "integer",
      label: "Kilometres run in 2024",
      delta: 0.23,
      deltaLabel: "vs 2023",
    },
    {
      kind: "quote",
      quote: "I started running before work in the spring.",
      attribution: "Club member",
    },
  ]}
  note="Illustrative data"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/story-deck.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/story-deck.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Timeline poster (`timeline-poster`)

> A poster of change over a run of periods: a full-width ribbon of bands whose thickness is each entity's value and whose order is its rank (`ribbon-chart`), a strip of two to four dated figures under it, and a bottom row with one measure per period as thick bars (`block-bar`) and one share at several dates as nested outlines (`nested-shares`).

- Component: `TimelinePoster` (import from `insightcharts`)
- Spec type: `"timeline-poster"`
- Level: template. Category: infographic.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when the subject is how 4 to 8 named things grew, shrank and changed places over 4 to 10 periods: electricity by source, library loans by format, commuters by mode. Give `hero` the periods and entities, `milestones` the dated numbers a reader should take away, `bars` one measure of the whole at each period and `shares` one share at a few dates. State the latest value in the title.

### Avoid

A single series over time (use `line-chart` or `area-chart` in a `poster`). Events with start and end dates (use `timeline-chart` or the `timeline-story` template). More than 8 entities or 10 periods, because the bands get too thin to label. Positions on one scale (use `scale-poster`). Parts of one subject at one date (use `radial-poster`).

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/timeline-poster
```

The file lands at `components/insightcharts/templates/timeline-poster.tsx`. `@insightcharts/timeline-poster-demo` adds a ready-made example next to it.

### Usage

```tsx
import { TimelinePoster } from "insightcharts";

<TimelinePoster
  theme="sunrise"
  kicker="Electricity"
  title="Wind supplied 8.6 TWh of Orrin Island's electricity in 2025"
  subtitle="Electricity generated on Orrin Island by source, terawatt-hours, every second year from 2015 to 2025."
  hero={{
    data: [
      { year: "2015", Coal: 9.2, Gas: 6.1, Hydro: 2.2, Wind: 1.4, Solar: 0.3 },
      { year: "2017", Coal: 8, Gas: 6.4, Hydro: 2.3, Wind: 2.6, Solar: 0.6 },
      { year: "2019", Coal: 6.1, Gas: 6, Hydro: 2.1, Wind: 4.3, Solar: 1.3 },
      { year: "2021", Coal: 4, Gas: 5.4, Hydro: 2.4, Wind: 5.9, Solar: 2.4 },
      { year: "2023", Coal: 2.3, Gas: 4.7, Hydro: 2.2, Wind: 7.4, Solar: 3.7 },
      { year: "2025", Coal: 1.1, Gas: 4, Hydro: 2.3, Wind: 8.6, Solar: 4.9 },
    ],
    x: "year",
    y: ["Coal", "Gas", "Hydro", "Wind", "Solar"],
    colorBy: "series",
    title: "Coal supplied 9.2 TWh in 2015",
  }}
  milestones={[
    { at: "2017", value: "62", label: "turbines started at the Skerry wind farm" },
    { at: "2021", value: "5.9 TWh", label: "came from wind", context: "Gas supplied 5.4 TWh" },
    { at: "2025", value: "1.1 TWh", label: "came from coal", context: "9.2 TWh in 2015" },
  ]}
  bars={{
    data: [
      { year: "2015", g: 520 },
      { year: "2017", g: 455 },
      { year: "2019", g: 370 },
      { year: "2021", g: 290 },
      { year: "2023", g: 215 },
      { year: "2025", g: 160 },
    ],
    name: "year",
    value: "g",
    format: "{value} g",
    marker: { after: "2017", label: "Skerry wind farm opened" },
    title: "A kilowatt-hour emitted 160 g of CO2 in 2025",
    subtitle: "Grams of CO2 per kilowatt-hour generated.",
  }}
  shares={{
    data: [
      { year: "2015", share: 9 },
      { year: "2019", share: 28 },
      { year: "2021", share: 41 },
      { year: "2025", share: 65 },
    ],
    name: "year",
    value: "share",
    highlight: "2025",
    wholeLabel: "All electricity generated",
    title: "Wind and solar supplied 65% of electricity in 2025",
  }}
  sources="Orrin Island Grid Office, annual generation statistics"
  note="Orrin Island is an invented place. All figures are illustrative."
  credit="InsightCharts"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "timeline-poster",
  "theme": "sunrise",
  "kicker": "Electricity",
  "title": "Wind supplied 8.6 TWh of Orrin Island's electricity in 2025",
  "subtitle": "Electricity generated on Orrin Island by source, terawatt-hours, every second year from 2015 to 2025.",
  "hero": {
    "data": [
      { "year": "2015", "Coal": 9.2, "Gas": 6.1, "Hydro": 2.2, "Wind": 1.4, "Solar": 0.3 },
      { "year": "2017", "Coal": 8, "Gas": 6.4, "Hydro": 2.3, "Wind": 2.6, "Solar": 0.6 },
      { "year": "2019", "Coal": 6.1, "Gas": 6, "Hydro": 2.1, "Wind": 4.3, "Solar": 1.3 },
      { "year": "2021", "Coal": 4, "Gas": 5.4, "Hydro": 2.4, "Wind": 5.9, "Solar": 2.4 },
      { "year": "2023", "Coal": 2.3, "Gas": 4.7, "Hydro": 2.2, "Wind": 7.4, "Solar": 3.7 },
      { "year": "2025", "Coal": 1.1, "Gas": 4, "Hydro": 2.3, "Wind": 8.6, "Solar": 4.9 }
    ],
    "x": "year",
    "y": ["Coal", "Gas", "Hydro", "Wind", "Solar"],
    "colorBy": "series",
    "title": "Coal supplied 9.2 TWh in 2015"
  },
  "milestones": [
    { "at": "2017", "value": "62", "label": "turbines started at the Skerry wind farm" },
    {
      "at": "2021",
      "value": "5.9 TWh",
      "label": "came from wind",
      "context": "Gas supplied 5.4 TWh"
    },
    { "at": "2025", "value": "1.1 TWh", "label": "came from coal", "context": "9.2 TWh in 2015" }
  ],
  "bars": {
    "data": [
      { "year": "2015", "g": 520 },
      { "year": "2017", "g": 455 },
      { "year": "2019", "g": 370 },
      { "year": "2021", "g": 290 },
      { "year": "2023", "g": 215 },
      { "year": "2025", "g": 160 }
    ],
    "name": "year",
    "value": "g",
    "format": "{value} g",
    "marker": { "after": "2017", "label": "Skerry wind farm opened" },
    "title": "A kilowatt-hour emitted 160 g of CO2 in 2025",
    "subtitle": "Grams of CO2 per kilowatt-hour generated."
  },
  "shares": {
    "data": [
      { "year": "2015", "share": 9 },
      { "year": "2019", "share": 28 },
      { "year": "2021", "share": 41 },
      { "year": "2025", "share": 65 }
    ],
    "name": "year",
    "value": "share",
    "highlight": "2025",
    "wholeLabel": "All electricity generated",
    "title": "Wind and solar supplied 65% of electricity in 2025"
  },
  "sources": "Orrin Island Grid Office, annual generation statistics",
  "note": "Orrin Island is an invented place. All figures are illustrative.",
  "credit": "InsightCharts"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `hero` (required) | `{ data, x, y, series?, values?, labels?, colorBy?, format?, highlight?, title?, ... } \| Slot` |  | The hero: one band per entity across the periods, drawn by `ribbon-chart`. Wide rows take `y` as a list of columns; long rows take `y` and `series`. A full spec or element replaces it. |
| `milestones` | `{ at: string; value: string; label: string; context?: string; icon?: string }[]` |  | Two to four dated figures in a strip under the hero, in time order. `at` is the period, printed in small capitals over the figure. |
| `bars` | `{ data, name, value, marker?, detail?, format?, title?, ... } \| Slot` |  | Bottom left: one measure at each period as thick bars with the numbers inside (`block-bar`). `marker: { after, label }` draws a dotted line after one period to mark an event. |
| `shares` | `{ data, name, value, wholeLabel?, highlight?, format?, title?, ... } \| Slot` |  | Bottom right: one share at 2 to 8 dates as outlines nested in one square (`nested-shares`). `format` defaults to `"{value}%"`. With only one of `bars` and `shares`, that one takes the full width. |
| `title` (required) | `string` |  | The poster's one fact, as a plain sentence with its number. |
| `kicker` | `string` |  | Small label above the title: the topic. |
| `subtitle` | `string` |  | One line under the title: the measure, population and period. |
| `theme` | `PosterThemeName \| string \| ThemeInput` | `"sunrise"` | Poster theme: `noir`, `magenta`, `dusk`, `ocean`, `forest`, `blueprint`, `sunrise`, `paper`, any other theme name, or a theme object. |
| `mode` | `"light" \| "dark" \| "auto" \| "system"` | `"light"` | Colour mode of the poster and everything in it. A poster paints its own ground and does not follow the page unless you set `auto`. Only `paper` has a different dark variant. |
| `download` | `boolean` | `false` | Show a "Download PNG" control under the poster that saves the whole poster as one image. |
| `maxWidth` | `number \| string` | `1100` | Widest the poster is drawn. It is centred in wider containers. |
| `linked` | `boolean` | `false` | Make the marks clickable. Clicking a mark in one graphic highlights the same name in every other graphic that has it, and filters the graphics that read the shared `data`. Click it again, or the empty ground of that graphic, to clear. |
| `data` | `DataInput` |  | Rows shared by every region whose config leaves out its own `data`. With `linked`, a click filters those regions. |
| `sources` | `string \| string[]` |  | Where the data comes from, shown in the footer. |
| `note` | `string` |  | Caveat shown in the footer, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the poster, shown at the right of the footer. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Heading level of the title. Panel headings are one level down. |

### Composition

- Composes: [poster](https://insightcharts.dev/llms/poster.md), [ribbon-chart](https://insightcharts.dev/llms/ribbon-chart.md), [block-bar](https://insightcharts.dev/llms/block-bar.md), [nested-shares](https://insightcharts.dev/llms/nested-shares.md)
- Used by: no molecule or template yet

### More examples

#### Paper, library loans, with download

```tsx
import { TimelinePoster } from "insightcharts";

<TimelinePoster
  theme="paper"
  download
  kicker="Libraries"
  title="Marlow's libraries lent 226,000 audiobooks in 2025"
  subtitle="Items lent by the Marlow library service by format, thousands, every third year from 2013 to 2025."
  hero={{
    data: [
      {
        year: "2013",
        "Printed books": 412,
        "E-books": 38,
        Audiobooks: 21,
        Films: 96,
        Magazines: 64,
      },
      {
        year: "2016",
        "Printed books": 371,
        "E-books": 84,
        Audiobooks: 47,
        Films: 71,
        Magazines: 52,
      },
      {
        year: "2019",
        "Printed books": 338,
        "E-books": 131,
        Audiobooks: 92,
        Films: 44,
        Magazines: 39,
      },
      {
        year: "2022",
        "Printed books": 296,
        "E-books": 187,
        Audiobooks: 158,
        Films: 23,
        Magazines: 31,
      },
      {
        year: "2025",
        "Printed books": 281,
        "E-books": 204,
        Audiobooks: 226,
        Films: 12,
        Magazines: 24,
      },
    ],
    x: "year",
    y: ["Printed books", "E-books", "Audiobooks", "Films", "Magazines"],
    colorBy: "series",
    format: "{value}k",
    title: "Printed-book loans fell from 412,000 to 281,000",
  }}
  milestones={[
    { at: "2013", value: "21k", label: "audiobooks were lent" },
    { at: "2022", value: "187k", label: "e-books were lent", context: "38,000 in 2013" },
    {
      at: "2025",
      value: "747k",
      label: "items were lent in all formats",
      context: "631,000 in 2013",
    },
  ]}
  bars={{
    data: [
      { year: "2013", k: 58 },
      { year: "2016", k: 61 },
      { year: "2019", k: 67 },
      { year: "2022", k: 74 },
      { year: "2025", k: 83 },
    ],
    name: "year",
    value: "k",
    format: "{value}k",
    title: "The service had 83,000 members in 2025",
  }}
  shares={{
    data: [{ year: "2013", share: 9 }, { year: "2019", share: 35 }, { year: "2025", share: 58 }],
    name: "year",
    value: "share",
    highlight: "2025",
    wholeLabel: "All loans",
    title: "E-books and audiobooks were 58% of loans in 2025",
  }}
  sources="Marlow library service, annual lending returns"
  note="The Marlow library service is invented. All figures are illustrative."
  credit="InsightCharts"
/>
```

#### Dusk, long-format rows, bars linked to the ribbon

```tsx
import { TimelinePoster } from "insightcharts";

<TimelinePoster
  theme="dusk"
  linked
  kicker="Commuting"
  title="24% of Kestrel Bay's commuters cycled to work in 2025"
  subtitle="Share of commuters by main mode of travel, per cent, 2010 to 2025."
  hero={{
    data: [
      { year: "2010", mode: "Car", share: 61 },
      { year: "2010", mode: "Bus", share: 17 },
      { year: "2010", mode: "Walking", share: 11 },
      { year: "2010", mode: "Train", share: 7 },
      { year: "2010", mode: "Bicycle", share: 4 },
      { year: "2015", mode: "Car", share: 54 },
      { year: "2015", mode: "Bus", share: 16 },
      { year: "2015", mode: "Walking", share: 11 },
      { year: "2015", mode: "Train", share: 10 },
      { year: "2015", mode: "Bicycle", share: 9 },
      { year: "2020", mode: "Car", share: 45 },
      { year: "2020", mode: "Bus", share: 13 },
      { year: "2020", mode: "Walking", share: 12 },
      { year: "2020", mode: "Train", share: 13 },
      { year: "2020", mode: "Bicycle", share: 17 },
      { year: "2025", mode: "Car", share: 37 },
      { year: "2025", mode: "Bus", share: 12 },
      { year: "2025", mode: "Walking", share: 12 },
      { year: "2025", mode: "Train", share: 15 },
      { year: "2025", mode: "Bicycle", share: 24 },
    ],
    x: "year",
    y: "share",
    series: "mode",
    colorBy: "series",
    format: "{value}%",
    title: "The car's share fell from 61% to 37%",
  }}
  milestones={[
    { at: "2010", value: "4%", label: "of commuters cycled" },
    { at: "2025", value: "24%", label: "of commuters cycled" },
  ]}
  bars={{
    data: [
      { mode: "Train", minutes: 41 },
      { mode: "Bus", minutes: 34 },
      { mode: "Car", minutes: 27 },
      { mode: "Bicycle", minutes: 19 },
      { mode: "Walking", minutes: 14 },
    ],
    name: "mode",
    value: "minutes",
    format: "{value} min",
    title: "The average train commute took 41 minutes in 2025",
    subtitle: "Average one-way commute by mode, minutes, 2025.",
  }}
  shares={{
    data: [
      { year: "2010", share: 15 },
      { year: "2015", share: 20 },
      { year: "2020", share: 29 },
      { year: "2025", share: 36 },
    ],
    name: "year",
    value: "share",
    highlight: "2025",
    wholeLabel: "All commuters",
    title: "36% of commuters walked or cycled in 2025",
  }}
  sources="Kestrel Bay travel-to-work survey"
  note="Kestrel Bay is an invented town. All figures are illustrative."
  credit="InsightCharts"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/timeline-poster.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/timeline-poster.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Timeline story (`timeline-story`)

> A story told in date order. It has a headline, one overview exhibit of the whole period (a timeline chart or an annotated line), dated chapters along a rail, a closing paragraph and a source note. Each chapter has a short text and an optional small exhibit.

- Component: `TimelineStory` (import from `insightcharts`)
- Spec type: `"timeline-story"`
- Level: template. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it when the reader needs the events in date order to understand a change. State the change over the whole period in the headline, with the numbers and dates. Mark the main events on the overview exhibit as annotations. Give each chapter one event. Add a small figure to a chapter only when it has a number to show. Mark the two or three most important events with `emphasis`.

### Avoid

Events with no measure that runs through the period (use a plain `annotated-timeline`). A comparison of two states with nothing in between (use `comparison-brief`). More than eight chapters. Merge minor events into the text of the chapter before or after.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/timeline-story
```

The file lands at `components/insightcharts/templates/timeline-story.tsx`. `@insightcharts/timeline-story-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, BigNumber, LineChart, TimelineStory } from "insightcharts";

<TimelineStory
  kicker="Energy"
  title="Coal generated 39% of Britain's electricity in 2012 and 0.6% in 2024"
  deck="The first public coal power station opened in 1882. The last coal plant closed on 30 September 2024."
  byline="By the data desk"
  date="2024-10-01"
  timeline={<LineChart
    data={[
      { year: "1990-01-01", share: 65 },
      { year: "1994-01-01", share: 50 },
      { year: "1998-01-01", share: 35 },
      { year: "2002-01-01", share: 32 },
      { year: "2006-01-01", share: 38 },
      { year: "2010-01-01", share: 28 },
      { year: "2012-01-01", share: 39 },
      { year: "2013-01-01", share: 36 },
      { year: "2014-01-01", share: 30 },
      { year: "2015-01-01", share: 22 },
      { year: "2016-01-01", share: 9 },
      { year: "2017-01-01", share: 7 },
      { year: "2018-01-01", share: 5 },
      { year: "2019-01-01", share: 2 },
      { year: "2020-01-01", share: 2 },
      { year: "2021-01-01", share: 2 },
      { year: "2022-01-01", share: 1.5 },
      { year: "2023-01-01", share: 1 },
      { year: "2024-01-01", share: 0.6 },
    ]}
    x="year"
    y="share"
    format="{value}%"
    zero
    area
    title="Coal's share of generation fell from 65% in 1990 to 0.6% in 2024"
    subtitle="Share of Great Britain's electricity generated from coal, 1990 to 2024"
    annotations={[
      { type: "band", axis: "x", from: "1990-01-01", to: "1998-01-01", label: "Gas plants built" },
      { type: "line", axis: "x", value: "2013-01-01", label: "Carbon price floor" },
      { type: "point", x: "2012-01-01", y: 39, label: "39% in 2012", position: "top" },
    ]}
    source="Department for Energy Security and Net Zero and National Grid ESO (rounded)"
    note="Figures are approximate, for illustration"
  />}
  intro="Coal's share fell in two periods. It fell from 65% to 35% between 1990 and 1998, when generators built gas plants. It fell from 39% to 9% between 2012 and 2016, after the carbon price floor was introduced."
  chapters={[
    {
      date: "1882",
      title: "The first public coal power station opens in London",
      text: "Thomas Edison's company built the plant at Holborn Viaduct. It supplied street lamps and nearby buildings.",
    },
    {
      date: "1990s",
      title: "Coal's share falls from 65% to 35% between 1990 and 1998",
      text: "Privatised generators built gas plants, which were cheaper and quicker to build than coal plants. Coal's share was between 28% and 39% from 1998 to 2013.",
    },
    {
      date: "April 2013",
      title: "The carbon price floor takes effect",
      emphasis: true,
      text: "The floor set a minimum price on power-station emissions. The rate doubled in 2015. Coal's share fell from 22% in 2015 to 9% in 2016.",
      exhibit: <BarChart
        data={[
          { year: "2012", share: 39 },
          { year: "2013", share: 36 },
          { year: "2014", share: 30 },
          { year: "2015", share: 22 },
          { year: "2016", share: 9 },
        ]}
        x="year"
        y="share"
        orientation="vertical"
        sort="none"
        highlight="2016"
        format="{value}%"
        height={170}
        subtitle="Coal share of generation, 2012 to 2016"
      />,
    },
    {
      date: "21 April 2017",
      title: "The first full day without coal since 1882",
      text: "Britain had 1 coal-free day in 2017. It had 180 in 2020.",
      exhibit: <BarChart
        data={[
          { year: "2017", days: 1 },
          { year: "2018", days: 21 },
          { year: "2019", days: 83 },
          { year: "2020", days: 180 },
        ]}
        x="year"
        y="days"
        orientation="vertical"
        sort="none"
        highlight="2020"
        height={170}
        subtitle="Coal-free days per year"
      />,
    },
    {
      date: "30 September 2024",
      title: "Ratcliffe-on-Soar, the last coal plant, shuts down",
      emphasis: true,
      text: "The plant had run since 1968. In 2024 wind generated 30% of the country's electricity and gas generated 26%.",
      exhibit: <BigNumber
        value="0%"
        label="Coal share of generation since October 2024"
        context="Britain was the first G7 country to end coal power"
      />,
    },
  ]}
  closing="Coal generated 0.6% of Britain's electricity in 2024, all of it before 30 September. Gas generated 26%."
  sources={["Digest of UK Energy Statistics", "National Grid ESO"]}
  period="1990 to 2024"
  note="Annual shares are rounded. Intermediate years before 2012 are interpolated for the chart. Figures are approximate, for illustration."
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "timeline-story",
  "kicker": "Energy",
  "title": "Coal generated 39% of Britain's electricity in 2012 and 0.6% in 2024",
  "deck": "The first public coal power station opened in 1882. The last coal plant closed on 30 September 2024.",
  "byline": "By the data desk",
  "date": "2024-10-01",
  "timeline": {
    "type": "line-chart",
    "data": [
      { "year": "1990-01-01", "share": 65 },
      { "year": "1994-01-01", "share": 50 },
      { "year": "1998-01-01", "share": 35 },
      { "year": "2002-01-01", "share": 32 },
      { "year": "2006-01-01", "share": 38 },
      { "year": "2010-01-01", "share": 28 },
      { "year": "2012-01-01", "share": 39 },
      { "year": "2013-01-01", "share": 36 },
      { "year": "2014-01-01", "share": 30 },
      { "year": "2015-01-01", "share": 22 },
      { "year": "2016-01-01", "share": 9 },
      { "year": "2017-01-01", "share": 7 },
      { "year": "2018-01-01", "share": 5 },
      { "year": "2019-01-01", "share": 2 },
      { "year": "2020-01-01", "share": 2 },
      { "year": "2021-01-01", "share": 2 },
      { "year": "2022-01-01", "share": 1.5 },
      { "year": "2023-01-01", "share": 1 },
      { "year": "2024-01-01", "share": 0.6 }
    ],
    "x": "year",
    "y": "share",
    "format": "{value}%",
    "zero": true,
    "area": true,
    "title": "Coal's share of generation fell from 65% in 1990 to 0.6% in 2024",
    "subtitle": "Share of Great Britain's electricity generated from coal, 1990 to 2024",
    "annotations": [
      {
        "type": "band",
        "axis": "x",
        "from": "1990-01-01",
        "to": "1998-01-01",
        "label": "Gas plants built"
      },
      { "type": "line", "axis": "x", "value": "2013-01-01", "label": "Carbon price floor" },
      { "type": "point", "x": "2012-01-01", "y": 39, "label": "39% in 2012", "position": "top" }
    ],
    "source": "Department for Energy Security and Net Zero and National Grid ESO (rounded)",
    "note": "Figures are approximate, for illustration"
  },
  "intro": "Coal's share fell in two periods. It fell from 65% to 35% between 1990 and 1998, when generators built gas plants. It fell from 39% to 9% between 2012 and 2016, after the carbon price floor was introduced.",
  "chapters": [
    {
      "date": "1882",
      "title": "The first public coal power station opens in London",
      "text": "Thomas Edison's company built the plant at Holborn Viaduct. It supplied street lamps and nearby buildings."
    },
    {
      "date": "1990s",
      "title": "Coal's share falls from 65% to 35% between 1990 and 1998",
      "text": "Privatised generators built gas plants, which were cheaper and quicker to build than coal plants. Coal's share was between 28% and 39% from 1998 to 2013."
    },
    {
      "date": "April 2013",
      "title": "The carbon price floor takes effect",
      "emphasis": true,
      "text": "The floor set a minimum price on power-station emissions. The rate doubled in 2015. Coal's share fell from 22% in 2015 to 9% in 2016.",
      "exhibit": {
        "type": "bar-chart",
        "data": [
          { "year": "2012", "share": 39 },
          { "year": "2013", "share": 36 },
          { "year": "2014", "share": 30 },
          { "year": "2015", "share": 22 },
          { "year": "2016", "share": 9 }
        ],
        "x": "year",
        "y": "share",
        "orientation": "vertical",
        "sort": "none",
        "highlight": "2016",
        "format": "{value}%",
        "height": 170,
        "subtitle": "Coal share of generation, 2012 to 2016"
      }
    },
    {
      "date": "21 April 2017",
      "title": "The first full day without coal since 1882",
      "text": "Britain had 1 coal-free day in 2017. It had 180 in 2020.",
      "exhibit": {
        "type": "bar-chart",
        "data": [
          { "year": "2017", "days": 1 },
          { "year": "2018", "days": 21 },
          { "year": "2019", "days": 83 },
          { "year": "2020", "days": 180 }
        ],
        "x": "year",
        "y": "days",
        "orientation": "vertical",
        "sort": "none",
        "highlight": "2020",
        "height": 170,
        "subtitle": "Coal-free days per year"
      }
    },
    {
      "date": "30 September 2024",
      "title": "Ratcliffe-on-Soar, the last coal plant, shuts down",
      "emphasis": true,
      "text": "The plant had run since 1968. In 2024 wind generated 30% of the country's electricity and gas generated 26%.",
      "exhibit": {
        "type": "big-number",
        "value": "0%",
        "label": "Coal share of generation since October 2024",
        "context": "Britain was the first G7 country to end coal power"
      }
    }
  ],
  "closing": "Coal generated 0.6% of Britain's electricity in 2024, all of it before 30 September. Gas generated 26%.",
  "sources": ["Digest of UK Energy Statistics", "National Grid ESO"],
  "period": "1990 to 2024",
  "note": "Annual shares are rounded. Intermediate years before 2012 are interpolated for the chart. Figures are approximate, for illustration."
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The change over the whole period, as one plain sentence with the numbers and dates in it. |
| `kicker` | `string` |  | Small label above the title. |
| `deck` | `string` |  | One-sentence standfirst. |
| `byline` | `string` |  | Author line. |
| `date` | `string` |  | Publication date. |
| `timeline` | `Slot` |  | The overview exhibit: a `timeline-chart` spec, or a `line-chart` with the events as `annotations`. Default height 360px for line charts. |
| `intro` | `string \| string[]` |  | A paragraph between the overview and the chapters. |
| `chaptersTitle` | `string` |  | Heading over the chapters. |
| `chapters` (required) | `{ date, title, text?, exhibit?, emphasis? }[]` |  | The dated chapters, oldest first. `date` is shown as written; `exhibit` is a small chart or figure; `emphasis` fills the marker for a major event. |
| `exhibitPosition` | `"below" \| "side"` | `"side"` | Where a chapter's exhibit sits; `side` falls back to `below` under 640px. |
| `closing` | `string \| string[]` |  | A closing paragraph that states the latest figures. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `maxWidth` | `number \| string` |  | Widest the piece may get. It is centred in wider containers. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [prose](https://insightcharts.dev/llms/prose.md), [annotated-timeline](https://insightcharts.dev/llms/annotated-timeline.md), [source-note](https://insightcharts.dev/llms/source-note.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [timeline-chart](https://insightcharts.dev/llms/timeline-chart.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md), [big-number](https://insightcharts.dev/llms/big-number.md)
- Used by: no molecule or template yet

### More examples

#### Sport: a timeline chart as the overview, exhibits below

```tsx
import { BigNumber, TimelineChart, TimelineStory } from "insightcharts";

<TimelineStory
  kicker="Athletics"
  title="The men's marathon record fell from 2:04:55 to 2:00:35 between 2003 and 2023"
  deck="Seven men held the record in that time. Carbon-plated shoes went on sale in 2017. The last two record-holders ran in them."
  exhibitPosition="below"
  timeline={<TimelineChart
    data={[
      { holder: "Paul Tergat, 2:04:55", from: "2003-09", to: "2007-09", lane: "Record" },
      { holder: "Haile Gebrselassie, 2:03:59", from: "2007-09", to: "2011-09", lane: "Record" },
      { holder: "Makau, Kipsang", from: "2011-09", to: "2014-09", lane: "Record" },
      { holder: "Dennis Kimetto, 2:02:57", from: "2014-09", to: "2018-09", lane: "Record" },
      { holder: "Eliud Kipchoge, 2:01:09", from: "2018-09", to: "2023-10", lane: "Record" },
      { holder: "Kelvin Kiptum, 2:00:35", from: "2023-10", to: "2025-06", lane: "Record" },
      { holder: "Carbon-plated shoes", from: "2017-05", to: "2025-06", lane: "Technology" },
      { holder: "Breaking2", from: "2017-05", lane: "Exhibition" },
      { holder: "1:59:40 in Vienna", from: "2019-10", lane: "Exhibition" },
    ]}
    name="holder"
    start="from"
    end="to"
    lane="lane"
    highlight={["Carbon-plated shoes", "Eliud Kipchoge, 2:01:09", "Kelvin Kiptum, 2:00:35"]}
    precision="month"
    title="The record fell by 142 seconds between 2014 and 2023"
    subtitle="Men's marathon world record holders and related events, 2003 to 2025"
    source="World Athletics"
  />}
  chapters={[
    {
      date: "September 2003",
      title: "Paul Tergat runs 2:04:55 in Berlin",
      text: "He was the first man to run a marathon in under 2:05.",
    },
    {
      date: "September 2008",
      title: "Haile Gebrselassie runs 2:03:59 in Berlin",
      text: "It was his second record in 12 months. He was 35.",
    },
    {
      date: "September 2014",
      title: "Dennis Kimetto runs 2:02:57 in Berlin",
      text: "The record stood for four years.",
    },
    {
      date: "May 2017",
      title: "Eliud Kipchoge runs 2:00:25 at the Breaking2 exhibition",
      emphasis: true,
      text: "The run used rotating pacemakers on a racing circuit, so it did not count as a record. Kipchoge wore prototype carbon-plated shoes. The shoes went on sale that summer.",
    },
    {
      date: "September 2018",
      title: "Eliud Kipchoge lowers the record by 78 seconds to 2:01:39",
      emphasis: true,
      text: "It was the largest single improvement since 1967. He ran 2:01:09 in 2022.",
      exhibit: <BigNumber
        value="−78 s"
        label="Improvement on Kimetto's record"
        context="The previous four records improved by 29 seconds on average"
      />,
    },
    {
      date: "October 2023",
      title: "Kelvin Kiptum runs 2:00:35 in Chicago",
      text: "It was his third marathon. He was 23. He died in a road accident four months later.",
    },
  ]}
  closing="No one has run under two hours in a record-eligible race. Kiptum's 2:00:35 is 35 seconds slower than two hours."
  sources="World Athletics record progression"
  note="Figures are approximate, for illustration"
  period="2003 to 2025"
/>
```

### Links

- Registry item: https://insightcharts.dev/r/timeline-story.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/timeline-story.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt

---

## Visual essay (`visual-essay`)

> 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.

- Component: `VisualEssay` (import from `insightcharts`)
- Spec type: `"visual-essay"`
- Level: template. Category: story.
- An HTML component: it takes only the props listed below, plus `theme`, `mode`, `className` and `style` where its source declares them. It does not take the common chart props.

### When to use

Use it for a finding that takes several charts and some text to explain. State the main finding with its number in the headline. Put the main figure within the first screen. Alternate text and charts, with two or three short paragraphs before each exhibit. In a scrolly block change one thing per step, such as the highlight, the year or an annotation. Use one accent colour for the subject in every chart.

### Avoid

A summary for someone who will not scroll (use `executive-brief`). Reference material read out of order (use `report-page`). More than one or two scrolly blocks. Use one only where the chart changes between steps.

### Install

From npm (the component ships in the package):

```bash
npm install insightcharts echarts
```

Or copy the source into your project with the shadcn CLI, so you can edit it (the engine still comes from the `insightcharts` package):

```bash
npx shadcn@latest registry add @insightcharts=https://insightcharts.dev/r/{name}.json   # once per project
npx shadcn@latest add @insightcharts/visual-essay
```

The file lands at `components/insightcharts/templates/visual-essay.tsx`. `@insightcharts/visual-essay-demo` adds a ready-made example next to it.

### Usage

```tsx
import { BarChart, LineChart, VisualEssay } from "insightcharts";

<VisualEssay
  kicker="Energy transition"
  title="Solar supplied 11.1% of EU electricity in 2024, more than coal's 9.8%"
  deck="Solar's share was 2.9% in 2015. Coal's share was 24.6% in 2015."
  byline="By the data desk"
  date="2025-03-14"
  blocks={[
    {
      kind: "prose",
      lead: true,
      text: "Solar supplied **2.9% of the EU's electricity** in 2015. Hydro supplied 11.5%.\n\nIn 2024 solar supplied 11.1%. It was the first full year in which solar generated more electricity than coal.",
    },
    {
      kind: "figure",
      chart: <LineChart
        data={[
          { year: "2015", Solar: 2.9, Coal: 24.6 },
          { year: "2016", Solar: 3, Coal: 22 },
          { year: "2017", Solar: 3.4, Coal: 20.6 },
          { year: "2018", Solar: 3.7, Coal: 19.2 },
          { year: "2019", Solar: 4.2, Coal: 15 },
          { year: "2020", Solar: 5, Coal: 13 },
          { year: "2021", Solar: 5.4, Coal: 14.7 },
          { year: "2022", Solar: 7, Coal: 15.8 },
          { year: "2023", Solar: 9.1, Coal: 12.3 },
          { year: "2024", Solar: 11.1, Coal: 9.8 },
        ]}
        x="year"
        y={["Solar", "Coal"]}
        highlight="Solar"
        format="{value}%"
        zero
        title="Solar's share rose from 2.9% to 11.1% between 2015 and 2024"
        subtitle="Share of EU electricity generation, 2015 to 2024"
        annotations={[
          { type: "band", axis: "x", from: "2021", to: "2022", label: "Gas price crisis" },
          { type: "point", x: "2016", y: 22, label: "Coal", position: "top", dot: false },
        ]}
        source="Ember, European Electricity Review 2025"
      />,
    },
    {
      kind: "prose",
      text: "Coal's share was 15.8% in 2022. It fell to 12.3% in 2023 and 9.8% in 2024. Solar's share rose from 7.0% to 11.1% in the same two years.",
    },
    {
      kind: "break",
      step: 1,
      total: 3,
      title: "Solar module prices, 2010 to 2024",
      text: "A module cost $2.00 a watt in 2010. It cost $0.11 a watt in 2024.",
    },
    {
      kind: "callout",
      chart: <LineChart
        data={[
          { year: "2010", usd: 2 },
          { year: "2012", usd: 0.9 },
          { year: "2014", usd: 0.65 },
          { year: "2016", usd: 0.5 },
          { year: "2018", usd: 0.3 },
          { year: "2020", usd: 0.22 },
          { year: "2022", usd: 0.26 },
          { year: "2024", usd: 0.11 },
        ]}
        x="year"
        y="usd"
        format={{ style: "currency", currency: "USD" }}
        zero
        area
        title="Solar module prices fell from $2.00 to $0.11 a watt between 2010 and 2024"
        subtitle="Average price of crystalline silicon solar modules, US dollars per watt"
        source="IRENA and BloombergNEF (rounded)"
      />,
      label: "Rooftop system cost",
      lead: "Modules are now the smaller part of the cost of a rooftop system",
      body: "Mounting, wiring, labour and the grid connection make up most of the cost.",
    },
    {
      kind: "stats",
      items: [
        {
          value: "338 GW",
          label: "Solar capacity installed in the EU, end of 2024",
          delta: "+66 GW",
          deltaLabel: "in 2024",
        },
        { value: "304 TWh", label: "Solar generation, 2024", delta: 0.22, deltaLabel: "vs 2023" },
        {
          value: "269 TWh",
          label: "Coal generation, 2024",
          delta: -0.16,
          deltaLabel: "vs 2023",
          upIsGood: false,
        },
      ],
    },
    {
      kind: "break",
      step: 2,
      total: 3,
      title: "EU electricity generation by source, 2015 and 2024",
      text: "Scroll to see the shares in 2015 and then in 2024.",
    },
    {
      kind: "scrolly",
      chart: <BarChart
        data={[
          { source: "Nuclear", y2015: 26.5, y2024: 23.7 },
          { source: "Coal", y2015: 24.6, y2024: 9.8 },
          { source: "Gas", y2015: 15.8, y2024: 15.7 },
          { source: "Hydro", y2015: 11.5, y2024: 12.5 },
          { source: "Wind", y2015: 9.3, y2024: 17.4 },
          { source: "Solar", y2015: 2.9, y2024: 11.1 },
        ]}
        x="source"
        y="y2015"
        sort="none"
        orientation="horizontal"
        format="{value}%"
        height={320}
        title="EU electricity generation by source, 2015"
        subtitle="Share of electricity generation"
        source="Ember, European Electricity Review 2025"
        option={{ xAxis: { max: 30 } }}
      />,
      stepHeight: "70vh",
      stickyTop: 16,
      steps: [
        {
          id: "baseline",
          label: "2015",
          content: "In 2015 **nuclear and coal** together supplied 51% of the EU's electricity.",
        },
        {
          id: "coal",
          content: "Coal supplied 24.6% in 2015. It was the second-largest source after nuclear.",
          highlight: "Coal",
        },
        {
          id: "coal-now",
          label: "2024",
          content: "Coal supplied 9.8% in 2024. Plants closed in Germany, Spain and Portugal.",
          highlight: "Coal",
          y: "y2024",
          title: "EU electricity generation by source, 2024",
        },
        {
          id: "solar",
          content: "**Solar** supplied 11.1% in 2024. It supplied 2.9% in 2015. Wind supplied 17.4% in 2024 and gas 15.7%.",
          highlight: "Solar",
          y: "y2024",
          title: "Solar supplied 11.1% of EU electricity in 2024",
        },
      ],
    },
    {
      kind: "quote",
      quote: "Solar was 1% of Dutch generation in 2015. It was 18% in 2024. We have had to change how we run the grid at midday.",
      attribution: "Marit de Vries",
      role: "Head of system operations at a Dutch grid operator",
    },
    {
      kind: "break",
      step: 3,
      total: 3,
      title: "Solar share by country",
      text: "Greece had the highest share in 2024 at 22.1%. Spain had 21.0%. France had 4.6%.",
    },
    {
      kind: "multiples",
      data: [
        { country: "Greece", year: "2015", share: 7.8 },
        { country: "Greece", year: "2018", share: 8.1 },
        { country: "Greece", year: "2021", share: 10.9 },
        { country: "Greece", year: "2024", share: 22.1 },
        { country: "Spain", year: "2015", share: 4.9 },
        { country: "Spain", year: "2018", share: 4.7 },
        { country: "Spain", year: "2021", share: 9.6 },
        { country: "Spain", year: "2024", share: 21 },
        { country: "Netherlands", year: "2015", share: 1 },
        { country: "Netherlands", year: "2018", share: 3.2 },
        { country: "Netherlands", year: "2021", share: 9.3 },
        { country: "Netherlands", year: "2024", share: 17.9 },
        { country: "Germany", year: "2015", share: 6 },
        { country: "Germany", year: "2018", share: 7.1 },
        { country: "Germany", year: "2021", share: 8.4 },
        { country: "Germany", year: "2024", share: 14.7 },
        { country: "Poland", year: "2015", share: 0 },
        { country: "Poland", year: "2018", share: 0.2 },
        { country: "Poland", year: "2021", share: 2.2 },
        { country: "Poland", year: "2024", share: 10.8 },
        { country: "France", year: "2015", share: 1.3 },
        { country: "France", year: "2018", share: 1.9 },
        { country: "France", year: "2021", share: 2.8 },
        { country: "France", year: "2024", share: 4.6 },
      ],
      facet: "country",
      x: "year",
      y: "share",
      highlight: ["Netherlands", "Poland"],
      format: "{value}%",
      columns: 3,
      title: "Solar's share in the Netherlands rose from 1.0% to 17.9% between 2015 and 2024",
      subtitle: "Solar share of electricity generation, 2015 to 2024, same scale in every panel",
      source: "Ember (country series rounded, illustrative)",
      width: "wide",
    },
    {
      kind: "prose",
      text: "Poland's solar share rose from 0.0% in 2015 to 10.8% in 2024. Retail electricity prices in the Netherlands and Poland rose after 2022. At those prices a rooftop system paid for itself in under seven years without subsidy.\n\nFrance has cheap nuclear power and slow permitting. Its solar share was 4.6% in 2024. Germany's was 14.7%.",
    },
  ]}
  sources={[
    { name: "Ember, European Electricity Review 2025", url: "https://ember-energy.org" },
    "IRENA Renewable Power Generation Costs",
    "BloombergNEF",
  ]}
  period="2010 to 2024, annual"
  method="Generation shares are of total net generation in the EU-27. Module prices are annual averages in nominal dollars."
  note="EU totals are approximate, rounded for illustration. Country series and the quotation are illustrative."
  credit="Analysis and charts by the data desk"
/>
```

### JSON spec

The same thing as data, rendered with `<Insight spec={spec} />`:

```json
{
  "type": "visual-essay",
  "kicker": "Energy transition",
  "title": "Solar supplied 11.1% of EU electricity in 2024, more than coal's 9.8%",
  "deck": "Solar's share was 2.9% in 2015. Coal's share was 24.6% in 2015.",
  "byline": "By the data desk",
  "date": "2025-03-14",
  "blocks": [
    {
      "kind": "prose",
      "lead": true,
      "text": "Solar supplied **2.9% of the EU's electricity** in 2015. Hydro supplied 11.5%.\n\nIn 2024 solar supplied 11.1%. It was the first full year in which solar generated more electricity than coal."
    },
    {
      "kind": "figure",
      "chart": {
        "type": "line-chart",
        "data": [
          { "year": "2015", "Solar": 2.9, "Coal": 24.6 },
          { "year": "2016", "Solar": 3, "Coal": 22 },
          { "year": "2017", "Solar": 3.4, "Coal": 20.6 },
          { "year": "2018", "Solar": 3.7, "Coal": 19.2 },
          { "year": "2019", "Solar": 4.2, "Coal": 15 },
          { "year": "2020", "Solar": 5, "Coal": 13 },
          { "year": "2021", "Solar": 5.4, "Coal": 14.7 },
          { "year": "2022", "Solar": 7, "Coal": 15.8 },
          { "year": "2023", "Solar": 9.1, "Coal": 12.3 },
          { "year": "2024", "Solar": 11.1, "Coal": 9.8 }
        ],
        "x": "year",
        "y": ["Solar", "Coal"],
        "highlight": "Solar",
        "format": "{value}%",
        "zero": true,
        "title": "Solar's share rose from 2.9% to 11.1% between 2015 and 2024",
        "subtitle": "Share of EU electricity generation, 2015 to 2024",
        "annotations": [
          { "type": "band", "axis": "x", "from": "2021", "to": "2022", "label": "Gas price crisis" },
          {
            "type": "point",
            "x": "2016",
            "y": 22,
            "label": "Coal",
            "position": "top",
            "dot": false
          }
        ],
        "source": "Ember, European Electricity Review 2025"
      }
    },
    {
      "kind": "prose",
      "text": "Coal's share was 15.8% in 2022. It fell to 12.3% in 2023 and 9.8% in 2024. Solar's share rose from 7.0% to 11.1% in the same two years."
    },
    {
      "kind": "break",
      "step": 1,
      "total": 3,
      "title": "Solar module prices, 2010 to 2024",
      "text": "A module cost $2.00 a watt in 2010. It cost $0.11 a watt in 2024."
    },
    {
      "kind": "callout",
      "chart": {
        "type": "line-chart",
        "data": [
          { "year": "2010", "usd": 2 },
          { "year": "2012", "usd": 0.9 },
          { "year": "2014", "usd": 0.65 },
          { "year": "2016", "usd": 0.5 },
          { "year": "2018", "usd": 0.3 },
          { "year": "2020", "usd": 0.22 },
          { "year": "2022", "usd": 0.26 },
          { "year": "2024", "usd": 0.11 }
        ],
        "x": "year",
        "y": "usd",
        "format": { "style": "currency", "currency": "USD" },
        "zero": true,
        "area": true,
        "title": "Solar module prices fell from $2.00 to $0.11 a watt between 2010 and 2024",
        "subtitle": "Average price of crystalline silicon solar modules, US dollars per watt",
        "source": "IRENA and BloombergNEF (rounded)"
      },
      "label": "Rooftop system cost",
      "lead": "Modules are now the smaller part of the cost of a rooftop system",
      "body": "Mounting, wiring, labour and the grid connection make up most of the cost."
    },
    {
      "kind": "stats",
      "items": [
        {
          "value": "338 GW",
          "label": "Solar capacity installed in the EU, end of 2024",
          "delta": "+66 GW",
          "deltaLabel": "in 2024"
        },
        {
          "value": "304 TWh",
          "label": "Solar generation, 2024",
          "delta": 0.22,
          "deltaLabel": "vs 2023"
        },
        {
          "value": "269 TWh",
          "label": "Coal generation, 2024",
          "delta": -0.16,
          "deltaLabel": "vs 2023",
          "upIsGood": false
        }
      ]
    },
    {
      "kind": "break",
      "step": 2,
      "total": 3,
      "title": "EU electricity generation by source, 2015 and 2024",
      "text": "Scroll to see the shares in 2015 and then in 2024."
    },
    {
      "kind": "scrolly",
      "chart": {
        "type": "bar-chart",
        "data": [
          { "source": "Nuclear", "y2015": 26.5, "y2024": 23.7 },
          { "source": "Coal", "y2015": 24.6, "y2024": 9.8 },
          { "source": "Gas", "y2015": 15.8, "y2024": 15.7 },
          { "source": "Hydro", "y2015": 11.5, "y2024": 12.5 },
          { "source": "Wind", "y2015": 9.3, "y2024": 17.4 },
          { "source": "Solar", "y2015": 2.9, "y2024": 11.1 }
        ],
        "x": "source",
        "y": "y2015",
        "sort": "none",
        "orientation": "horizontal",
        "format": "{value}%",
        "height": 320,
        "title": "EU electricity generation by source, 2015",
        "subtitle": "Share of electricity generation",
        "source": "Ember, European Electricity Review 2025",
        "option": { "xAxis": { "max": 30 } }
      },
      "stepHeight": "70vh",
      "stickyTop": 16,
      "steps": [
        {
          "id": "baseline",
          "label": "2015",
          "content": "In 2015 **nuclear and coal** together supplied 51% of the EU's electricity."
        },
        {
          "id": "coal",
          "content": "Coal supplied 24.6% in 2015. It was the second-largest source after nuclear.",
          "highlight": "Coal"
        },
        {
          "id": "coal-now",
          "label": "2024",
          "content": "Coal supplied 9.8% in 2024. Plants closed in Germany, Spain and Portugal.",
          "highlight": "Coal",
          "y": "y2024",
          "title": "EU electricity generation by source, 2024"
        },
        {
          "id": "solar",
          "content": "**Solar** supplied 11.1% in 2024. It supplied 2.9% in 2015. Wind supplied 17.4% in 2024 and gas 15.7%.",
          "highlight": "Solar",
          "y": "y2024",
          "title": "Solar supplied 11.1% of EU electricity in 2024"
        }
      ]
    },
    {
      "kind": "quote",
      "quote": "Solar was 1% of Dutch generation in 2015. It was 18% in 2024. We have had to change how we run the grid at midday.",
      "attribution": "Marit de Vries",
      "role": "Head of system operations at a Dutch grid operator"
    },
    {
      "kind": "break",
      "step": 3,
      "total": 3,
      "title": "Solar share by country",
      "text": "Greece had the highest share in 2024 at 22.1%. Spain had 21.0%. France had 4.6%."
    },
    {
      "kind": "multiples",
      "data": [
        { "country": "Greece", "year": "2015", "share": 7.8 },
        { "country": "Greece", "year": "2018", "share": 8.1 },
        { "country": "Greece", "year": "2021", "share": 10.9 },
        { "country": "Greece", "year": "2024", "share": 22.1 },
        { "country": "Spain", "year": "2015", "share": 4.9 },
        { "country": "Spain", "year": "2018", "share": 4.7 },
        { "country": "Spain", "year": "2021", "share": 9.6 },
        { "country": "Spain", "year": "2024", "share": 21 },
        { "country": "Netherlands", "year": "2015", "share": 1 },
        { "country": "Netherlands", "year": "2018", "share": 3.2 },
        { "country": "Netherlands", "year": "2021", "share": 9.3 },
        { "country": "Netherlands", "year": "2024", "share": 17.9 },
        { "country": "Germany", "year": "2015", "share": 6 },
        { "country": "Germany", "year": "2018", "share": 7.1 },
        { "country": "Germany", "year": "2021", "share": 8.4 },
        { "country": "Germany", "year": "2024", "share": 14.7 },
        { "country": "Poland", "year": "2015", "share": 0 },
        { "country": "Poland", "year": "2018", "share": 0.2 },
        { "country": "Poland", "year": "2021", "share": 2.2 },
        { "country": "Poland", "year": "2024", "share": 10.8 },
        { "country": "France", "year": "2015", "share": 1.3 },
        { "country": "France", "year": "2018", "share": 1.9 },
        { "country": "France", "year": "2021", "share": 2.8 },
        { "country": "France", "year": "2024", "share": 4.6 }
      ],
      "facet": "country",
      "x": "year",
      "y": "share",
      "highlight": ["Netherlands", "Poland"],
      "format": "{value}%",
      "columns": 3,
      "title": "Solar's share in the Netherlands rose from 1.0% to 17.9% between 2015 and 2024",
      "subtitle": "Solar share of electricity generation, 2015 to 2024, same scale in every panel",
      "source": "Ember (country series rounded, illustrative)",
      "width": "wide"
    },
    {
      "kind": "prose",
      "text": "Poland's solar share rose from 0.0% in 2015 to 10.8% in 2024. Retail electricity prices in the Netherlands and Poland rose after 2022. At those prices a rooftop system paid for itself in under seven years without subsidy.\n\nFrance has cheap nuclear power and slow permitting. Its solar share was 4.6% in 2024. Germany's was 14.7%."
    }
  ],
  "sources": [
    { "name": "Ember, European Electricity Review 2025", "url": "https://ember-energy.org" },
    "IRENA Renewable Power Generation Costs",
    "BloombergNEF"
  ],
  "period": "2010 to 2024, annual",
  "method": "Generation shares are of total net generation in the EU-27. Module prices are annual averages in nominal dollars.",
  "note": "EU totals are approximate, rounded for illustration. Country series and the quotation are illustrative.",
  "credit": "Analysis and charts by the data desk"
}
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` (required) | `string` |  | The essay's main finding, as one plain sentence with the number and the period in it. |
| `kicker` | `string` |  | Small label above the title. |
| `deck` | `string` |  | One-sentence standfirst. |
| `byline` | `string` |  | Author line. |
| `date` | `string` |  | Publication date. ISO dates are formatted for the locale. |
| `blocks` (required) | `(Block \| Slot)[]` |  | The story in reading order. Each block has a `kind`: `prose` `{ text, lead? }`; `figure` `{ chart, caption? }`; `callout` `{ chart, lead, body, label?, tone?, side? }`; `scrolly` `{ chart, steps, cumulative?, scrollMode?, side?, stepHeight? }` (the props of `scrolly-chart`); `quote` `{ quote, attribution?, role? }`; `stats` `{ items, title? }`; `multiples` `{ facet, ... }` (props of `small-multiples`, or of `small-multiple-grid` when it has a `chart`); `break` `{ title, step?, total?, text? }`. Any block takes `width: "text" \| "wide" \| "full"` and an `id`. A bare chart spec is treated as a wide figure. |
| `measure` | `number` | `680` | Width of the reading column in px. |
| `textSize` | `"md" \| "lg"` |  | Body text size. Default 18px, 16px in narrow containers. |
| `sources` | `string \| { name, url? } \| (string \| { name, url? })[]` |  | Where the data comes from, shown in the closing source note. Entries with a `url` are linked. |
| `period` | `string` |  | The period the data covers. |
| `method` | `string` |  | How the numbers were produced: definitions, adjustments, exclusions. |
| `note` | `string` |  | Caveats the reader should know, e.g. "Illustrative data". |
| `credit` | `string` |  | Who made the piece. |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level of the title; section headings follow one level down. |
| `maxWidth` | `number \| string` |  | Widest the piece may get. It is centred in wider containers. |
| `theme` | `ThemeInput` |  | Theme override, passed on to everything inside. |
| `mode` | `"auto" \| "system" \| "light" \| "dark"` | `"auto"` | Colour mode, passed on to everything inside. |

### Composition

- Composes: [headline](https://insightcharts.dev/llms/headline.md), [prose](https://insightcharts.dev/llms/prose.md), [pull-quote](https://insightcharts.dev/llms/pull-quote.md), [step-marker](https://insightcharts.dev/llms/step-marker.md), [small-multiples](https://insightcharts.dev/llms/small-multiples.md), [chart-callout](https://insightcharts.dev/llms/chart-callout.md), [scrolly-chart](https://insightcharts.dev/llms/scrolly-chart.md), [small-multiple-grid](https://insightcharts.dev/llms/small-multiple-grid.md), [stat-row](https://insightcharts.dev/llms/stat-row.md), [source-note](https://insightcharts.dev/llms/source-note.md), [line-chart](https://insightcharts.dev/llms/line-chart.md), [bar-chart](https://insightcharts.dev/llms/bar-chart.md)
- Used by: no molecule or template yet

### More examples

#### Transport: a shorter essay without a scrolly

```tsx
import { BarChart, LineChart, VisualEssay } from "insightcharts";

<VisualEssay
  kicker="Cities"
  title="Cycling accounts for 11.2% of trips in Paris and cars for 4.3%"
  deck="Bicycle counts in 2024 were 3.2 times the 2015 level. The city made 50 km of temporary pandemic cycle lanes permanent."
  byline="By the transport desk"
  date="2025-04-02"
  textSize="md"
  blocks={[
    {
      kind: "prose",
      lead: true,
      text: "Permanent counters in Paris recorded 3.2 times as many bicycles in 2024 as in 2015. The count rose 47% between 2019 and 2020.",
    },
    {
      kind: "figure",
      chart: <LineChart
        data={[
          { year: "2015", index: 100 },
          { year: "2016", index: 104 },
          { year: "2017", index: 108 },
          { year: "2018", index: 118 },
          { year: "2019", index: 154 },
          { year: "2020", index: 226 },
          { year: "2021", index: 241 },
          { year: "2022", index: 262 },
          { year: "2023", index: 288 },
          { year: "2024", index: 317 },
        ]}
        x="year"
        y="index"
        zero
        title="Bicycle counts in Paris in 2024 were 3.2 times the 2015 level"
        subtitle="Bicycle counts at permanent counters, index (2015 = 100)"
        annotations={[
          { type: "line", axis: "x", value: "2020", label: "Temporary lanes open" },
          { type: "point", x: "2024", y: 317, label: "3.2 times\nthe 2015 level", position: "left" },
        ]}
        source="City of Paris counter data (rounded, illustrative)"
      />,
    },
    {
      kind: "prose",
      text: "The index rose from 154 in 2019 to 226 in 2020, when the city opened 50 km of temporary lanes. The city kept those lanes and built 130 km more. The index reached 317 in 2024.",
    },
    {
      kind: "quote",
      quote: "Counts went up on the streets where we built protected lanes. They stayed up after the lockdowns ended.",
      attribution: "A city transport planner",
    },
    {
      kind: "callout",
      chart: <BarChart
        data={[
          { mode: "Walking", share: 53.5 },
          { mode: "Public transport", share: 30 },
          { mode: "Cycling", share: 11.2 },
          { mode: "Car", share: 4.3 },
          { mode: "Other", share: 1 },
        ]}
        x="mode"
        y="share"
        sort="none"
        orientation="horizontal"
        format="{value}%"
        highlight="Cycling"
        title="Cycling's share of trips within Paris is 2.6 times the car's"
        subtitle="Share of trips within Paris by main mode, 2023"
        source="Institut Paris Region mobility survey"
      />,
      lead: "Walking accounts for 53.5% of trips within Paris",
      body: "Public transport accounts for 30.0%. Cycling accounts for 11.2% and cars for 4.3%.",
      tone: "neutral",
    },
    {
      kind: "prose",
      text: "These shares are for trips within the city. In the suburbs the car accounts for one trip in three.",
    },
  ]}
  sources={["City of Paris open data", "Institut Paris Region"]}
  period="2015 to 2024"
  note="Counter index is illustrative. Mode shares are approximate, for illustration."
/>
```

### Links

- Registry item: https://insightcharts.dev/r/visual-essay.json
- Source: https://github.com/insightcharts/insightcharts/blob/main/packages/insightcharts/src/templates/visual-essay.tsx
- Spec schema: https://insightcharts.dev/schema/insight-spec.json
- Choosing a form: https://insightcharts.dev/llms/guides/choosing-a-form.md
- All components: https://insightcharts.dev/llms.txt