# HeatmapChart

Heatmap Chart component for matrix-style data visualization.

## Example[​](#example "Direct link to Example")

```tsx
"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[​](#heatmapchart-1 "Direct link to 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`](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/charts/heatmap/index.tsx)

### Props[​](#props "Direct link to 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[​](#usage "Direct link to Usage")

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

<HeatmapChart /* props */ />

```
