# 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.

Install with `npm install insightcharts echarts`, or copy component source with the shadcn CLI from the `@insightcharts` registry. Charts take `data` plus field names (`x`, `y`, `series`), a `title`, and optional `highlight` and `annotations`. Write `title` as 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 as a plain label. The full writing rules are in "Choosing a form". Any component can also be a JSON spec `{ "type": "bar-chart", ... }` rendered by `<Insight spec>`. Templates with the category `infographic` are the Infographics set. Each one draws a designed poster on a painted ground from one spec with a poster theme (see the "Infographics" guide). Use only the component names listed here. Start with the quickstart and "Choosing a form".

## Guides

- [Quickstart](https://insightcharts.dev/llms/guides/quickstart.md): Install, render a first chart, and the rules for server and client components.
- [Choosing a form](https://insightcharts.dev/llms/guides/choosing-a-form.md): A decision table from what the data has to show to the component, the rules for writing titles and text, and the design rules every InsightCharts figure follows.
- [Common chart props](https://insightcharts.dev/llms/guides/common-props.md): The props every chart built with defineChart accepts, generated from CommonChartProps.
- [Data](https://insightcharts.dev/llms/guides/data.md): Every shape the data prop accepts, how loading works, and every JSON transform.
- [Theming and dark mode](https://insightcharts.dev/llms/guides/theming.md): Theme tokens, the --ic-* CSS variables, shadcn integration, colour modes and restyling the chrome.
- [Crossfiltering with InsightData](https://insightcharts.dev/llms/guides/crossfiltering.md): Share one dataset between charts and let a click on one filter the others.
- [Scroll and swipe stories with Scrolly](https://insightcharts.dev/llms/guides/stories.md): Scrolly keeps one graphic in place and changes its state as the reader moves through a list of text steps.
- [Infographics](https://insightcharts.dev/llms/guides/infographics.md): When to choose a poster over a report-style template, how to write an infographic spec, the poster frame and its panels, the eight poster themes, the poster primitives, icons, PNG download and the phone layout.
- [Export](https://insightcharts.dev/llms/guides/export.md): The export menu, programmatic export through a ref, formats and what each contains.
- [The JSON spec](https://insightcharts.dev/llms/guides/json-spec.md): Describe any component as JSON, render it with Insight, validate it with the schema.
- [Recipes](https://insightcharts.dev/llms/guides/recipes.md): Short, complete patterns for common jobs, using only the stable API.

## Atoms

- [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 bars](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

- [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 and 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 with 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 with 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

- [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.

## Machine-readable

- [Spec JSON Schema](https://insightcharts.dev/schema/insight-spec.json): validates any `<Insight spec>` object
- [Component manifest](https://insightcharts.dev/schema/manifest.json): every component's metadata, props and example as JSON
- [shadcn registry](https://insightcharts.dev/r/registry.json): installable items; one built item at `https://insightcharts.dev/r/<name>.json`

## Optional

- [Everything in one file](https://insightcharts.dev/llms-full.txt): all guides and component pages concatenated
- [Agent skill](https://github.com/insightcharts/insightcharts/tree/main/skills/insightcharts): install with `npx skills add insightcharts/insightcharts` or `npx shadcn@latest add @insightcharts/agent-skill`