Skip to content
InsightCharts

Search

Search guides and components

Heatmap

Colours a category-by-category (or time-by-category) grid by a numeric value, using a sequential or diverging scale.

Use when
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 when
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).

Preview

Orders peak at 70 per hour at 12pm on Wednesdays

Average orders per hour by weekday and time of day

Illustrative data

Composition

  1. Atoms61
  2. Molecules19
  3. Templates20

Used in

No molecule or template lists heatmap in its composes. It still fits any slot that takes a component.

Installation

$ pnpm dlx shadcn@latest add @insightcharts/heatmap

The CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:

import { Heatmap } from "insightcharts";

Examples

Missing cells (cohort triangle)

Share of each signup cohort still active

By months since signup, January to August cohorts

Illustrative data. Hatched cells have not happened yet.

Diverging around zero

Temperature anomaly by region and decade, 1900s to 2010s

Difference from the 20th-century mean, °C

Illustrative data

Stress: 18 by 24, highlighted row, a gap

Trips started per hour by station

Weekday average, 18 stations. Station 18 is highlighted. Station 08 has no data from 10:00 to 13:00.

Illustrative data

Props

PropTypeDefaultDescription
xrequiredstringColumn field: a category or a date.
yrequiredstringRow field.
valuerequiredstringNumeric field that colours each cell. One data row per cell.
divergingbooleanfalseDiverging palette centred on midpoint, for values with a meaningful middle.
midpointnumber0Centre of the diverging scale.
labelsbooleanPrint 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 chart props 29

Every chart built with defineChart accepts these on top of its own props.

PropTypeDescription
dataDataInputRows, CSV text, a URL, { url, path }, an async function, or an Arrow-style table. Omit inside <InsightData>.
transformTransform | Transform[]A pipeline of transforms applied before drawing.
titlestringThe 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.
subtitlestringMeasure, unit, population, period.
sourcestringData source, shown as "Source: ...".
notestringMethod notes or caveats.
heightnumber | stringCSS height of the plot. Default 360.
aspectnumberWidth / height. Overrides height.
highlightstring | string[]The entity (or entities) the title is about. Every other series is drawn in grey.
annotationsAnnotation[]Reference lines, shaded bands and callouts, in data coordinates.
formatFormatSpecHow to print values: "compact", "percent", "currency:USD", "{value} kg", Intl options, or a function.
legendbooleanShow the legend. Default: shown when there are two or more series.
selectboolean | stringMake 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) => voidCalled with the selected values whenever the selection changes.
optionEChartsOption | ((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.
themeThemeInputA theme, or a partial set of tokens merged over the surrounding theme, for this chart only.
modeModeInput"auto" (default) follows the page, "system" follows the OS, or force "light" / "dark".
rendererRendererInput"auto" (default) uses SVG for light charts and canvas for heavy ones.
animatebooleanSet false to disable animation. Reduced-motion preferences are always respected.
lazybooleanMount the chart only when it scrolls near the viewport. Default true.
groupstringLink tooltips with other charts sharing this group id.
exportableboolean | ExportFormat[]Show an export menu: true or a list of formats from png, jpeg, svg, pdf, csv, json.
tablebooleanShow a collapsible "View data" table under the chart.
altstringAccessible description: the chart type and measures, then the main pattern and the notable values.
idstringStable id for this chart's selection in the shared store.
onEventsRecord<string, ChartEventHandler>ECharts event handlers, e.g. { click: (params, chart) => {} }. Prefix a name with zr: to bind to the canvas itself.
onReady(chart: EChartsInstance) => voidCalled with the ECharts instance once it is created.
classNamestringClass name for the outer <figure>.
styleCSSPropertiesInline style for the outer <figure>.