# Heat map

A grid of cells coloured by value, for spotting hot and cold combinations.

- Component: `<HeatMap />`, imported from `em-kit`
- Required props: `rowDimension`, `columnDimension`, `measure` and `results`
- HTML page, with live previews: https://emkit.embeddable.com/docs/components/heat-map
- Playground (needs a browser): https://emkit.embeddable.com/docs/components/heat-map/playground

`HeatMap` takes `rowDimension` + `columnDimension` + `measure`. Its siblings name their fields differently: `PivotTable` takes `rowDimension` + `columnDimension` + `measures`.

## Install

```bash
npm install em-kit
pnpm add em-kit   # or, with pnpm
yarn add em-kit   # or, with yarn
bun add em-kit   # or, with bun
```

`react` and `react-dom` 19.1.1 or later are the only peer dependencies; Chart.js installs with the package. Wrap your app, or the part with charts, in `<ChartsProvider>` once: without it every chart throws `EmKit components must be rendered inside <ChartsProvider>.` Every example on this page includes `<ChartsProvider>` so that it runs on its own: if your app already has one, delete it from the example. A chart fills its parent, so the parent needs a height. In the Next.js App Router, every file that renders `ChartsProvider` or a chart starts with `'use client'`, and the provider pins the locale, `theme={{ formatter: { locale: 'en-US' } }}`, so the server and the browser format numbers alike. On a server-rendered page, pass the heat map’s colours (`minColor`, `midColor`, `maxColor` or a theme chart colour) as hex, such as `'#f4f0ff'`: a named, `rgb()` or `var()` colour renders black on the server, and React keeps it. The default colours are hex and match. [The quick start](/docs/quick-start.md#in-the-nextjs-app-router) has the Next.js files.

## Usage

```tsx
import { ChartsProvider, HeatMap, dimension, measure, results } from 'em-kit';

const industry = dimension({ name: 'industry', title: 'Industry' });
const plan = dimension({ name: 'plan', title: 'Plan' });
const customers = measure({ name: 'customers', title: 'Customers' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 320 }}>
      <HeatMap
        title="Customers by industry and plan"
        rowDimension={industry}
        columnDimension={plan}
        measure={customers}
        results={results(rows)}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { plan: 'Starter', industry: 'Health', customers: 133 },
  { plan: 'Growth', industry: 'Health', customers: 224 },
  { plan: 'Enterprise', industry: 'Health', customers: 91 },
  { plan: 'Starter', industry: 'Media', customers: 438 },
  { plan: 'Growth', industry: 'Media', customers: 220 },
  { plan: 'Enterprise', industry: 'Media', customers: 19 },
  { plan: 'Starter', industry: 'Retail', customers: 465 },
  { plan: 'Growth', industry: 'Retail', customers: 245 },
  { plan: 'Enterprise', industry: 'Retail', customers: 31 },
  { plan: 'Starter', industry: 'Tech', customers: 246 },
  { plan: 'Growth', industry: 'Tech', customers: 395 },
  { plan: 'Enterprise', industry: 'Tech', customers: 66 },
];
```

## States

The chart draws its own states from `results`: a skeleton while `isLoading` is true and it has no rows, a spinner in the header while it reloads rows it already has, an empty state when `data` is `[]`, and the message when `error` is set. Pass your query’s state straight through.

## Examples

### Custom colour scale

Your own cold, middle and hot colours. `minColor`, `midColor` and `maxColor`; the cell text switches between dark and light for contrast.

```tsx
import { ChartsProvider, HeatMap, dimension, measure, results } from 'em-kit';

const industry = dimension({ name: 'industry', title: 'Industry' });
const plan = dimension({ name: 'plan', title: 'Plan' });
const customers = measure({ name: 'customers', title: 'Customers' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 320 }}>
      <HeatMap
        title="Customers by industry and plan"
        rowDimension={industry}
        columnDimension={plan}
        measure={customers}
        results={results(rows)}
        minColor="#ecfeff"
        midColor="#22d3ee"
        maxColor="#155e75"
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { plan: 'Starter', industry: 'Health', customers: 133 },
  { plan: 'Growth', industry: 'Health', customers: 224 },
  { plan: 'Enterprise', industry: 'Health', customers: 91 },
  { plan: 'Starter', industry: 'Media', customers: 438 },
  { plan: 'Growth', industry: 'Media', customers: 220 },
  { plan: 'Enterprise', industry: 'Media', customers: 19 },
  { plan: 'Starter', industry: 'Retail', customers: 465 },
  { plan: 'Growth', industry: 'Retail', customers: 245 },
  { plan: 'Enterprise', industry: 'Retail', customers: 31 },
  { plan: 'Starter', industry: 'Tech', customers: 246 },
  { plan: 'Growth', industry: 'Tech', customers: 395 },
  { plan: 'Enterprise', industry: 'Tech', customers: 66 },
];
```

### Thresholds

Everything in the bottom fifth of the range fully cold and the top fifth fully hot, so outliers don’t wash out the rest. Thresholds take a raw value or a percentage of the range: `minThreshold: '20%'`, `maxThreshold: '80%'`.

```tsx
import { ChartsProvider, HeatMap, dimension, measure, results } from 'em-kit';

const industry = dimension({ name: 'industry', title: 'Industry' });
const plan = dimension({ name: 'plan', title: 'Plan' });
const customers = measure({ name: 'customers', title: 'Customers' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 320 }}>
      <HeatMap
        title="Customers by industry and plan"
        rowDimension={industry}
        columnDimension={plan}
        measure={customers}
        results={results(rows)}
        minThreshold="20%"
        maxThreshold="80%"
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { plan: 'Starter', industry: 'Health', customers: 133 },
  { plan: 'Growth', industry: 'Health', customers: 224 },
  { plan: 'Enterprise', industry: 'Health', customers: 91 },
  { plan: 'Starter', industry: 'Media', customers: 438 },
  { plan: 'Growth', industry: 'Media', customers: 220 },
  { plan: 'Enterprise', industry: 'Media', customers: 19 },
  { plan: 'Starter', industry: 'Retail', customers: 465 },
  { plan: 'Growth', industry: 'Retail', customers: 245 },
  { plan: 'Enterprise', industry: 'Retail', customers: 31 },
  { plan: 'Starter', industry: 'Tech', customers: 246 },
  { plan: 'Growth', industry: 'Tech', customers: 395 },
  { plan: 'Enterprise', industry: 'Tech', customers: 66 },
];
```

### Colours only

No numbers in the cells, for a compact pattern view; the values stay in the exports.

```tsx
import { ChartsProvider, HeatMap, dimension, measure, results } from 'em-kit';

const industry = dimension({ name: 'industry', title: 'Industry' });
const plan = dimension({ name: 'plan', title: 'Plan' });
const customers = measure({ name: 'customers', title: 'Customers' });

export const Example = () => (
  <ChartsProvider>
    <div style={{ height: 320 }}>
      <HeatMap
        title="Customers by industry and plan"
        rowDimension={industry}
        columnDimension={plan}
        measure={customers}
        results={results(rows)}
        showValues={false}
      />
    </div>
  </ChartsProvider>
);

const rows = [
  { plan: 'Starter', industry: 'Health', customers: 133 },
  { plan: 'Growth', industry: 'Health', customers: 224 },
  { plan: 'Enterprise', industry: 'Health', customers: 91 },
  { plan: 'Starter', industry: 'Media', customers: 438 },
  { plan: 'Growth', industry: 'Media', customers: 220 },
  { plan: 'Enterprise', industry: 'Media', customers: 19 },
  { plan: 'Starter', industry: 'Retail', customers: 465 },
  { plan: 'Growth', industry: 'Retail', customers: 245 },
  { plan: 'Enterprise', industry: 'Retail', customers: 31 },
  { plan: 'Starter', industry: 'Tech', customers: 246 },
  { plan: 'Growth', industry: 'Tech', customers: 395 },
  { plan: 'Enterprise', industry: 'Tech', customers: 66 },
];
```

## Props

Required props come first. A blank default means the prop is unset unless you pass it.

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `rowDimension` | `Dimension` | yes |  | The dimension down the side of the grid. |
| `columnDimension` | `Dimension` | yes |  | The dimension across the top of the grid. |
| `measure` | `Measure` | yes |  | The number behind each cell’s colour and label. |
| `results` | `DataResponse` | yes |  | Your query’s state: `{ isLoading, data, error }`, where `data` is your rows. `results(rows)` builds it from an array. |
| `columnWidth` | `number` | no |  | A fixed width for the value columns, in pixels. |
| `displayNullAs` | `string` | no |  | Text shown where a value is null, for example `"–"`. |
| `firstColumnWidth` | `number` | no |  | A fixed width for the row-label column, in pixels. |
| `maxColor` | `string` | no |  | Colour of the highest values. |
| `maxThreshold` | `string` | no |  | Values at this get `maxColor`; values above it darken further. A number as a string, or a percentage of the range such as `"80%"`. |
| `midColor` | `string` | no |  | Colour of the values in the middle of the range. |
| `minColor` | `string` | no |  | Colour of the lowest values. |
| `minThreshold` | `string` | no |  | Values at this get `minColor`; values below it fade further towards white. A number as a string (`"100"`), or a percentage of the range such as `"20%"`. |
| `showValues` | `boolean` | no | `true` | Print the value in each cell. |
| `onCellClicked` | `(args: HeatMapOptionsClickArg) => void` | no |  | Called with the clicked cell’s row and column values. |
| `componentName` | `string` | no |  | A name for this component, included in the interaction events it dispatches on the DOM, for your analytics. |
| `trackingId` | `string` | no |  | An id included in the same events, to tell two instances apart. |
| `title` | `string` | no |  | The card’s title. A `"key\|fallback"` string is looked up in your translations. |
| `description` | `string` | no |  | Smaller text under the title. Translates like `title`. |
| `tooltip` | `string` | no |  | Text for an info icon beside the title. |
| `hideMenu` | `boolean` | no | `false` | Hide the card’s header: the title, description and menu. |
| `menuOptions` | `("csv" \| "xlsx" \| "png" \| "maximize")[]` | no | `["csv", "xlsx", "png", "maximize"]` | Which entries the card menu offers. Pass `[]` for none. |

```ts
type HeatMapOptionsClickArg = { rowDimensionValue: string | undefined; rowDimensionTimeRange: TimeRange; columnDimensionValue: string | undefined; columnDimensionTimeRange: TimeRange; }
type TimeRange = { from: Date | undefined; to: Date | undefined; relativeTimeString?: string; } | undefined
```

Each is exported from `em-kit` as a type, for example `import type { HeatMapOptionsClickArg } from 'em-kit'`.

A click payload’s `TimeRange` is `undefined` unless the clicked field is a time dimension, and its `relativeTimeString` is always `undefined`, so read it as `range?.from`. When you pass one, `from` and `to` are enough.

## Field options

Options go in a field’s `inputs`, for example `measure({ name: 'revenue', inputs: { prefix: '$' } })`. Every field takes `prefix`, `suffix`, `decimalPlaces`, `currency`, `abbreviateLargeNumber`, `displayName` and `maxCharacters`. A time dimension in `rowDimension` or `columnDimension` also takes `granularity`, `dateBounds` and `ignoreEmptyDate`. Its `granularity` is what labels the axis as dates and fills periods with no row; `dimension()` takes it in `inputs` or at the top level, `dimension({ granularity: 'month' })`. [Field options](/docs/describing-your-data.md#field-options) describes them.

## Keyboard

| Key | Where | What it does |
|---|---|---|
| `Tab`, `Shift` + `Tab` | Grid | Moves from cell to cell: every cell takes focus. |
| `Enter` or `Space` | Cell | Calls `onCellClicked` with the cell’s row and column values, if you passed it. |

The card menu’s keys, and what is still missing, are in [Accessibility](/docs/accessibility.md#keyboard).
