HeatmapChart

Key for the numeric value that determines cell color.

Flat array of row objects keyed by field name.

Container height in pixels. Width is always responsive.

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

Key for Y-axis categories (rows).

Item selection. true = single selection keyed by the default key.

Accessible name, description, data table and keyboard navigation. No announcements: it switches <Chart>'s interaction announcements, which this family does not make.

The entrance: none by default; type opts in to 'wipe' or 'fade'. There are no series to stagger, update, layer or exit.

Optional className applied to the outer container.

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.

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

The context menu. Opened on a cell, the host's builder receives a typed HeatmapCell ({datum, x, y, value}) as context.target.element; a sparse cell's "Copy value" is disabled.

The initial selection of an uncontrolled chart.

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

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.

Cell label configuration.

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 shown in tooltips.

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

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.

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 configuration: enabled, renderer, valueFormatter, style. The heatmap has no tooltip modes, snapping or pinning.

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.

Optional fixed width in pixels. Default: fill container.

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

The row axis (T5): as xAxis; a row label wraps to up to three lines as its row allows, and never turns.

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.

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.

Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative ChartHandle calls.

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

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

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