React API Reference

Import the public API from @taewooyo/heatmap-react:

import { Heatmap, computeHeatmapLayout } from "@taewooyo/heatmap-react";
import { useHeatmapState } from "@taewooyo/heatmap-react";
import type { HeatmapProps, HeatmapNode, HeatmapLayoutOptions, HeatmapLayoutCell, HeatmapDisplayPolicy, HeatmapInteraction, HeatmapMotion, HeatmapStyle } from "@taewooyo/heatmap-react";

HeatmapNode

The input must not contain cycles. metric changes color but not area. The core does not fetch imageUrl.

Heatmap props

HeatmapProps extends HeatmapLayoutOptions and adds these component props:

Compose-aligned configuration

React uses SVG pixels where Compose uses Dp. The configuration objects share Compose's setting names and corresponding defaults.

The older flat props (metricFormatter, selectedBorderColor, and tooltipHoverDelayMs) remain supported. Values in the configuration objects take precedence. Hover tooltips default to off, like Compose.

useHeatmapState(root)

Use this hook when React should manage drill-down and leaf selection like Compose:

const state = useHeatmapState(data);

<Heatmap data={data} state={state} width={960} height={600} />

It exposes visibleNode, breadcrumbs, selectedNode, selectedId, canNavigateUp, and the same navigation/selection operations as Compose: drillDown, navigateUp, navigateTo, navigateToBreadcrumb, reset, select, isSelected, and clearSelection.

The component uses SVG with adaptive text and optional round images. Fill changes use a 240 ms CSS transition. Hover tooltips are opt-in through interaction.showTooltipOnHover; the application owns touch detail presentation.

HeatmapLayoutOptions

computeHeatmapLayout(root, options)

Use the pure layout entry point without rendering React:

const cells = computeHeatmapLayout(market, { width: 960, height: 480 });
const visibleLeaves = cells.filter((cell) => cell.visible && cell.isLeaf);

It returns readonly HeatmapLayoutCell[] in tree traversal order. Each cell has the original node, path-derived key, parentIndex (-1 at the root), depth, x, y, width, height, computed CSS hex color, isLeaf, and visible. Invisible cells should not be drawn. key distinguishes identical IDs in different branches.

Invalid dimensions, metric values, colors, cycles, or duplicate sibling IDs throw an error. The component uses this function internally; consumers normally only need Heatmap.

For Kotlin/Compose APIs, use the separate Kotlin API Reference and generated Dokka reference.

Version 0.3.0 additions

• ResponsiveHeatmap accepts containerStyle and containerClassName instead of explicit width/height. Supply a bounded height. fallback is rendered before measurement or while hidden.
• emptyContent is shown when no positive visual items exist; the default is No data.
• The source value is included in accessible names by default. valueFormatter changes its text, and valueLabel localizes the accessible label.
• state.navigationPath and state.navigateToPath(path) use root-relative ID arrays.
• state.drillDown(node) opens an exact nested group from the current data. Strings address direct children.

Updates with the same root ID retain valid paths and selection. A different root ID resets both. motion.enabled = false also disables fill-color transitions.