---
id: "packages/active-charts/all-exports/heatmap-chart"
title: "HeatmapChart"
description: "HeatmapChart, HeatmapAxisConfig, HeatmapChartProps: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/heatmap-chart"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:heatmap-chart"
---

# HeatmapChart

Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports).

## `HeatmapChart`

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `colorKey` | `string` | yes | Key for the numeric value that determines cell color. |
| `data` | `TDatum[]` | yes | Flat array of row objects keyed by field name. |
| `height` | `number` | yes | Container height in pixels. Width is always responsive. |
| `xKey` | `string` | yes | X-axis field name. Every Cartesian chart reads this to place rows along the x-axis. The y-axis field name is chart-specific: either top-level `yKey` (single-series shorthand) or `series[i].yKey` (multi-series). |
| `yKey` | `string` | yes | Key for Y-axis categories (rows). |
| `accessibility` | `StandaloneAccessibilityOptions` | no | Accessible name, description, data table and keyboard navigation. No `announcements`: it switches `<Chart>`'s interaction announcements, which this family does not make. |
| `animation` | `StandaloneAnimationOption<"type">` | no | The entrance: none by default; `type` opts in to `'wipe'` or `'fade'`. There are no series to stagger, update, layer or exit. |
| `className` | `string` | no | Optional className applied to the outer container. |
| `colorLegend` | `FeatureOption<ColorLegendOptions>` | no | The colour key under (or beside) the matrix: the numeric gradient, or the class legend of a `'classes'` scale. Shown by default; `false` (or `{enabled: false}`) hides it. |
| `colorScale` | `QuantitativeColorScale` | no | How a value becomes a colour (CF1, BC-Q1, T5): a sequential or diverging scale with ends fixed by the host or taken from the data and its own `colors`; colour stops at values (`type: 'stops'`); or named classes (`type: 'classes'`), shown as a class legend and named in the tooltip, the data table and the announcement. Fixed ends make heatmaps comparable: equal values get equal colours. A value beyond an end takes that end's colour, keeps its own value everywhere it is shown, and the scale marks the end `≤` or `≥`. See {@link QuantitativeColorScale}. |
| `contextMenu` | `FeatureOption<ChartContextMenuOptions<HeatmapCell<TDatum>, "copy" \| "export">>` | no | The context menu. Opened on a cell, the host's builder receives a typed {@link HeatmapCell} (`{datum, x, y, value}`) as `context.target.element`; a sparse cell's "Copy value" is disabled. |
| `defaultSelectedItems` | `readonly ChartItemRef[]` | no | The initial selection of an uncontrolled chart. |
| `dir` | `"ltr" \| "rtl"` | no | The chart's UI direction: the reading direction of its HTML text and chrome (tooltip, legend, menus, the accessible table), and the direction the context menu carries under `<body>`.  Left out, the chart inherits the direction of the page around it (the nearest `dir` attribute, else the computed CSS direction) and follows a later change of that attribute. It is never inferred from `locale`, and it never reverses an axis or reorders data: `reversed` stays an explicit axis choice. Under `rtl` the chrome mirrors (legend flow, tooltip side, context menu and submenus, report text in exports), a title-like label starts at the inline start, and a label placed by geometry (an axis tick, a slice or bar label) keeps its physical side; plot arrow keys stay spatial while legend and menu arrows follow the reading direction. |
| `events` | `(Omit<ChartEvents, "onLegendChange" \| "onZoomChange"> & ChartSelectionEvents<TDatum, ChartCellItem<TDatum>>)` | no | Events; the heatmap neither zooms nor has a series legend. The selection events (T8) report a cell of a row as `{kind: 'cell', x, y}`, its row's `xKey` and `yKey` values, with the row as `datum`. |
| `highlight` | `{ recede?: boolean; }` | no | The heatmap's attention (W-FV-4, amended by W-CF-2). By default no cell changes while one is addressed. `{recede: true}` lets the other cells step back mildly, at Active's near context step, while the pointer or the keyboard is on a cell; the addressed cell, every label, the gutter cues and the scale marker stay as they are. Never under forced colours and never in an export. Default: `false`. |
| `label` | `HeatmapLabelOptions` | no | Cell label configuration. |
| `locale` | `ValuePresentation` | no | Presentation input for axis labels, tooltips, labels and accessibility announcements: a locale code (notation follows the language), or a presentation-context object (`{languageLocale, dateShape?, dateFormat?, timeFormat?, numberFormat?, currencyDisplay?}`) carrying language and notation independently. `dateShape` is the normal human date shape a plain date consumer inherits; an axis that declares its own preset for readability keeps it. Forwarded untouched to the central `@workspace/active-format`; the package never resolves tenant or application settings itself. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no `'en'` fallback, active-format D14). Object inputs must be referentially stable across renders. |
| `name` | `string` | no | Name shown in tooltips. |
| `onAnimationComplete` | `((event: AnimationCompleteEvent) => void)` | no | Fired when a chart animation completes. - `'load'`: initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active). - `'update'`: data-update transition finished.  Not triggered by zoom animations (use `onZoomChange`) or tooltip fades. |
| `onExportComplete` | `((result: ChartExportResult) => void)` | no | Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative `ChartHandle` calls. |
| `onExportError` | `((format: ChartExportFormat, error: unknown) => void)` | no | Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (`<ChartDefaults diagnostics>`). |
| `onItemActivate` | `((item: ChartCellItem<TDatum>, source: ChartInteractionSource) => void)` | no | Fired when the reader activates an item: a click or tap on it, or `Enter` on the focused item (`Shift+Enter` on a sankey, whose `Enter` moves between nodes and links). With a handler, `Enter` activates instead of opening the context menu (`Shift+F10` and the context-menu key still open it). |
| `onReady` | `(() => void)` | no | Fired exactly once per chart instance, after the first successful mount with valid dimensions and **before** any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests.  Distinct from {@link onAnimationComplete} with `type: 'load'`, which fires *after* the load animation finishes. A chart with `animation={false}` still fires `onReady` — animation state has no effect on readiness.  A new React `key` on the host produces a new component instance and `onReady` fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance).  **Consumer requirement — stable from first render.** The latch closes on the first effect run regardless of whether `onReady` was defined at that moment. If `onReady` is initially `undefined` and later resolves to a function, the callback will **never** fire — the latch has already closed with a no-op. Pass a stable reference (typically via `useCallback`) or pass the final function unconditionally from the first render. |
| `onSelectionChange` | `((selection: ChartItemRef[], change: ChartSelectionChange<TDatum, ChartCellItem<TDatum>>) => void)` | no | Fired when the reader changes the selection (pointer, touch or keyboard), and when an uncontrolled selection drops items the data no longer contains. `selection` is the complete selection the change makes; it keeps every reference the selection held, of whatever form. On a controlled chart it is a proposal (`change.requested: true`), computed from the current `selectedItems` and never from an earlier proposal; the host applies it, changes it or ignores it. |
| `ref` | `Ref<ChartExportHandle>` | no | Imperative handle: exports and element access. The heatmap has no data-range zoom, so its handle has no `setZoom`. Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `selectedItems` | `readonly ChartItemRef[]` | no | The selection, controlled by the host. The chart draws, announces and lists the items it resolves to and never changes it; the host updates it from `onSelectionChange`. A request the host applies is announced when the host passes it back; one it ignores is never announced. A reference to an item that is hidden, zoomed or drilled out of view, or not in the data stays in the host's selection and is not shown as selected. |
| `selection` | `FeatureOption<Omit<ChartSelectionOptions, "itemKey">>` | no | Item selection. `true` = single selection keyed by the default key. |
| `t` | `ChartTranslateFn` | no | The host translator for every text the chart shows or announces. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028). |
| `tooltip` | `StandaloneTooltipOption` | no | Tooltip configuration: `enabled`, `renderer`, `valueFormatter`, `style`. The heatmap has no tooltip modes, snapping or pinning. |
| `valueSemantics` | `ChartValueSemantics` | no | What the cell values mean (BC1): unit and precision, declared once with the type the Cartesian charts read (`ChartValueSemantics`). The cell labels, the colour scale's end labels, the tooltip, the data table and the announcement write each value in it. The label's own `formatter` or `format` still wins for the labels and the scale, `tooltip.valueFormatter` for the tooltip; without a declaration the chart presentation's number applies. A missing value stays "no value", a value beyond a fixed scale end keeps its true number; CSV and Copy value keep the raw number. |
| `width` | `number` | no | Optional fixed width in pixels. Default: fill container. |
| `xAxis` | `HeatmapAxisConfig` | no | The column axis (T5): its title, its labels' text and room, and the order of the columns. Default: the columns in the order they first appear, labelled by their value, wrapped or turned where they do not fit. See {@link HeatmapAxisConfig}. |
| `yAxis` | `Omit<HeatmapAxisConfig, "autoRotate">` | no | The row axis (T5): as `xAxis`; a row label wraps to up to three lines as its row allows, and never turns. |

## Types

**HeatmapAxisConfig**

```ts
interface HeatmapAxisConfig {
  title?: string;
  formatter?: (category: string, raw: unknown) => string;
  temporalSemantic?: TemporalSemantic;
  order?: readonly ChartItemKey[];
  reversed?: boolean;
  wrap?: number;
  autoRotate?: boolean;
}
```

One axis of a heatmap (T5): a matrix gutter, never a numeric axis, so it
takes no domain, ticks, grid or zoom. Every category keeps its label: a
label wraps, then turns (columns, `autoRotate`), then is cut once with
its full name as its title; it never shrinks and is never skipped. The
order it sets is the one every reader follows: the cells, the labels, the
keyboard, the tooltip, the data table and the export.

**HeatmapChartProps**

```ts
interface HeatmapChartProps<TDatum extends ChartDatum = ChartDatum>
  extends
    Omit<
      CartesianChartProps<TDatum>,
      | 'contextMenu'
      | 'colors'
      | 'onZoomChange'
      | 'onLegendChange'
      | 'events'
      | 'tooltip'
      | 'animation'
      | 'accessibility'
      | 'ref'
    >,
    ChartSelectionProps<
      TDatum,
      ChartCellItem<TDatum>,
      Omit<ChartSelectionOptions, 'itemKey'>
    > {
  ref?: Ref<ChartExportHandle>;
  accessibility?: StandaloneAccessibilityOptions;
  tooltip?: StandaloneTooltipOption;
  animation?: StandaloneAnimationOption<'type'>;
  events?: Omit<ChartEvents, 'onZoomChange' | 'onLegendChange'> &
    ChartSelectionEvents<TDatum, ChartCellItem<TDatum>>;
  yKey: string;
  xAxis?: HeatmapAxisConfig;
  yAxis?: Omit<HeatmapAxisConfig, 'autoRotate'>;
  colorKey: string;
  colorScale?: QuantitativeColorScale;
  highlight?: {recede?: boolean};
  label?: HeatmapLabelOptions;
  name?: string;
  colorLegend?: FeatureOption<ColorLegendOptions>;
  contextMenu?: FeatureOption<
    ChartContextMenuOptions<HeatmapCell<TDatum>, 'copy' | 'export'>
  >;
  valueSemantics?: ChartValueSemantics;
}
```

Props for {@link HeatmapChart}. Extends {@link CartesianChartProps}
(adds `data`, `xKey`) and {@link BaseChartProps}.

Heatmap renders through its own standalone pipeline (no `<Chart>`
delegation) but honours the full wrapper contract, so `<ChartDefaults>`
context propagates identically to cartesian charts.

Entrance animation: supports `wipe` (left→right reveal)
and `fade`. Default is `none` — heatmaps often carry a lot of cells and
a timed reveal on every render would be noisy; consumers opt in via
`animation={{entrance: {type: 'wipe'}}}`. Reduced-motion is honoured defensively
via the global media query in `accessibility.css`.

Feature surfaces Heatmap does NOT support today (legend, crosshairs,
zoom, navigator, sync, dataGrouping) are intentionally absent from the
interface.