HeatmapChart

Heatmap Chart component for matrix-style data visualization.

Example

"use client";

import { HeatmapChart } from "@databricks/appkit-ui/react";

export default function HeatmapChartExample() {
  const data = [];
  const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
  const hours = ["00:00", "04:00", "08:00", "12:00", "16:00", "20:00"];

  for (const day of days) {
    for (const hour of hours) {
      data.push({
        day,
        hour,
        count: Math.floor(Math.random() * 100),
      });
    }
  }

  return (
    <HeatmapChart
      data={data}
      xKey="day"
      yAxisKey="hour"
      yKey="count"
      height={300}
    />
  );
}

HeatmapChart

Heatmap Chart component for matrix-style data visualization.

Important: This component uses Apache ECharts architecture. Configure it via props, not by passing child components.

Best Practice: Use the built-in data fetching by passing queryKey and parameters props instead of pre-fetching data with useAnalyticsQuery.

Data should be in "long format" with three fields:

• xKey: X-axis category (columns)
• yAxisKey: Y-axis category (rows)
• yKey: The numeric value for each cell

Supports both query mode (queryKey + parameters) and data mode (static data).

Source: packages/appkit-ui/src/react/charts/heatmap/index.tsx

Props

Prop	Type	Required	Default	Description
queryKey	string		-	Analytics query key registered with analytics plugin
parameters	Record<string, unknown>		-	Query parameters passed to the analytics endpoint
format	enum		"auto"	Data format to use - "json": Use JSON format (smaller payloads, simpler) - "arrow": Use Arrow format (faster for large datasets) - "auto": Automatically select based on expected data size
transformer	(<T>(data: T) => T)		-	Transform raw data before rendering
data	ChartData		-	Arrow Table or JSON array
title	string		-	Chart title
showLegend	boolean		-	Show legend
colorPalette	enum		-	Color palette to use. Auto-selected based on chart type if not specified. - "categorical": Distinct colors for different categories (bar, pie, line) - "sequential": Gradient for magnitude/intensity (heatmap) - "diverging": Two-tone for positive/negative values
colors	string[]		-	Custom colors for series (overrides colorPalette)
height	number		300	Chart height in pixels
className	string		-	Additional CSS classes
xKey	string		-	X-axis field key. Auto-detected from schema if not provided.
yKey	string | string[]		-	Y-axis field key(s). Auto-detected from schema if not provided.
ariaLabel	string		-	Accessibility label for screen readers
testId	string		-	Test ID for automated testing
options	Record<string, unknown>		-	Additional ECharts options to merge
yAxisKey	string		-	Field key for the Y-axis categories. For heatmaps, data should have: xKey (column), yAxisKey (row), and yKey (value).
min	number		-	Min value for color scale (auto-detected if not provided)
max	number		-	Max value for color scale (auto-detected if not provided)
showLabels	boolean		false	Show value labels on cells

Usage

import { HeatmapChart } from '@databricks/appkit-ui';

<HeatmapChart /* props */ />