> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# Heatmap

> Visualize data density across two dimensions with the Heatmap component.

API reference: [Heatmap()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.heatmap/index.md) (function), [IHeatmapProps](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapprops/index.md) (interface)

A **heatmap** represents data as a matrix where individual values are represented as colors. Heatmaps can help you discover trends and understand complex datasets, for example, website traffic by page and time.

![Heatmap of sales by menu category and location state, darker cells for higher values](https://www.gooddata.ai/docs/gooddata-ui/gd-ui/heatmap.png)

## [Buckets](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/heatmap/#buckets)

| Prop | Required | Takes | What it does |
| --- | --- | --- | --- |
| `measure` | Yes | One measure | Sets the value, and so the color, of each cell. |
| `rows` | No | One attribute | Creates one row per attribute value. |
| `columns` | No | One attribute | Creates one column per attribute value. |
| `filters` | No | Filters | Limits the data the heatmap shows. |

## [Sorting](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/heatmap/#sorting)

Without `sortBy`, the heatmap sorts the data by the `rows` attribute in descending order. You can pass `sortBy` to sort the data differently.

## [Configuration](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/heatmap/#configuration)

Pass these options in the `config` prop. See [Chart configuration](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/chart-config/index.md) for details.

| Option | What it changes |
| --- | --- |
| `colors`, `colorPalette`, `colorMapping` | Base color of the cells. The heatmap takes the first color, or the color that `colorMapping` assigns to the measure, splits the values into seven equal ranges, and gives each range a shade of that color. |
| `legend` | Whether the legend shows and where. The legend shows the value range of each shade. |
| `dataLabels` | `visible` shows or hides the cell values. `style: "backplate"` adds a background behind them. |
| `xaxis`, `yaxis` | The X axis (`columns`) and the Y axis (`rows`). `visible`, `labelsEnabled`, `rotation`, and `name` set how the axis, its labels, and its name show. |
| `zoomInsight` | `true` lets you zoom in along the X axis and pan while holding Shift. |
| `separators` | Thousands and decimal separators in the number format. |

The following example shows the `config` structure with sample values:

```ts
import type { IChartConfig } from "@gooddata/sdk-ui-charts";

const config: IChartConfig = {
    xaxis: {
        visible: true,
        labelsEnabled: true,
        rotation: "auto"
    },
    yaxis: {
        visible: true,
        labelsEnabled: true,
        rotation: "auto"
    },
    legend: {
        enabled: true,
        position: "top"
    },
    dataLabels: {
        visible: "auto"
    },
    separators: {
        thousand: ",",
        decimal: "."
    }
};
```

## [Limits](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/heatmap/#limits)

- A heatmap renders up to 10,000 cells. With more, the chart shows an error and `onError` receives a [`DataTooLargeToDisplaySdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.datatoolargetodisplaysdkerror/index.md). Filter the data to fit.
- With 150 or more cells, the heatmap hides the data labels, even if `dataLabels.visible` is `true`.

## [Structure](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/heatmap/#structure)

```tsx
import "@gooddata/sdk-ui-charts/styles/css/main.css";
import { Heatmap } from "@gooddata/sdk-ui-charts";

<Heatmap
    measure={<measure>}
    rows={<attribute>}
    columns={<attribute>}
    config={<chart-config>}
    …
/>
```

## [Example](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/heatmap/#example)

```tsx
import "@gooddata/sdk-ui-charts/styles/css/main.css";
import { Heatmap } from "@gooddata/sdk-ui-charts";
import * as Md from "./catalog.js";

<div style={{ height: 300 }}>
    <Heatmap
        measure={Md.$TotalSales}
        rows={Md.LocationState}
        columns={Md.MenuCategory}
    />
</div>
```

## [Props](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/heatmap/#props)

| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`measure`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md#iheatmapbucketpropsmeasure) | [`AttributeMeasureOrPlaceholder`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.attributemeasureorplaceholder/index.md) | Yes | Specify measure whose values will be charted on the heatmap. | [`IHeatmapBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md) |
| [`backend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ibucketchartprops/index.md#ibucketchartpropsbackend) | [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | No | Analytical backend, from which the chart will obtain data to visualize If you do not specify instance of analytical backend using this prop, then you MUST have BackendProvider up in the component tree. | [`IBucketChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ibucketchartprops/index.md) |
| [`columns`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md#iheatmapbucketpropscolumns) | [`AttributeOrPlaceholder`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.attributeorplaceholder/index.md) | No | Specify attribute, whose values will be used to create columns in the heatmap. | [`IHeatmapBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md) |
| [`config`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md#icommonchartpropsconfig) | [`IChartConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ichartconfig/index.md) | No | Configure chart's behavior and appearance. | [`ICommonChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md) |
| [`drillableItems`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropsdrillableitems) | [`ExplicitDrill`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.explicitdrill/index.md)`[]` | No | Configure drillability; e.g. which parts of the visualization can be interacted with. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`ErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropserrorcomponent) | `ComponentType<`[`IErrorProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ierrorprops/index.md)`>` | No | React component to display in the event when there is an error with either obtaining the data from backend or with the data itself. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`execConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md#icommonchartpropsexecconfig) | [`IExecutionConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iexecutionconfig/index.md) | No | Execution configuration, will provide the execution with necessary config before initiating execution. | [`ICommonChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md) |
| [`exportTitle`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropsexporttitle) | `string` | No | Set title to use for exported files. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`filters`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md#iheatmapbucketpropsfilters) | [`NullableFiltersOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.nullablefiltersorplaceholders/index.md) | No | Specify filters to apply on the data to chart. | [`IHeatmapBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md) |
| [`height`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md#icommonchartpropsheight) | `number` | No | Set height of the chart (in pixels). | [`ICommonChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md) |
| [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropsloadingcomponent) | `ComponentType<`[`ILoadingProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iloadingprops/index.md)`>` | No | React component to display while loading data from the backend. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`locale`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md#ivisualizationpropslocale) | `string` | No | Set Locale for visualization localization. | [`IVisualizationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationprops/index.md) |
| [`onDataView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksondataview) | [`OnDataView`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ondataview/index.md) | No | _(Alpha)_ Called when the visualization loads a DataView, i.e. it receives data from the backend. | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`onDrill`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksondrill) | [`OnFiredDrillEvent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.onfireddrillevent/index.md) | No | Called when user triggers a drill on a visualization. | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`onError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksonerror) | [`OnError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.onerror/index.md) | No | Called when an error occurs while loading data for the visualization. | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`onExportReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksonexportready) | [`OnExportReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.onexportready/index.md) | No | Called when the visualization is ready to be exported. | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`onLegendReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ichartcallbacks/index.md#ichartcallbacksonlegendready) | [`OnLegendReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.onlegendready/index.md) | No | Called when legend is rendered. | [`IChartCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ichartcallbacks/index.md) |
| [`onLoadingChanged`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md#ivisualizationcallbacksonloadingchanged) | [`OnLoadingChanged`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.onloadingchanged/index.md) | No | Called when loading status of the visualization changes - vis starts or stops loading | [`IVisualizationCallbacks`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.ivisualizationcallbacks/index.md) |
| [`placeholdersResolutionContext`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md#iheatmapbucketpropsplaceholdersresolutioncontext) | `any` | No | Resolution context for composed placeholders. | [`IHeatmapBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md) |
| [`rows`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md#iheatmapbucketpropsrows) | [`AttributeOrPlaceholder`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.attributeorplaceholder/index.md) | No | Specify attribute, whose values will be used to create rows in the heatmap. | [`IHeatmapBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md) |
| [`sortBy`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md#iheatmapbucketpropssortby) | [`SortsOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.sortsorplaceholders/index.md) | No | Specify how to sort the data to chart. | [`IHeatmapBucketProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.iheatmapbucketprops/index.md) |
| [`width`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md#icommonchartpropswidth) | `number` | No | Set width of the chart (in pixels). | [`ICommonChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.icommonchartprops/index.md) |
| [`workspace`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ibucketchartprops/index.md#ibucketchartpropsworkspace) | `string` | No | Identifier of analytical workspace, from which the chart will obtain data to visualize. If you do not specify workspace identifier, then you MUST have WorkspaceProvider up in the component tree. | [`IBucketChartProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-charts/sdk-ui-charts.ibucketchartprops/index.md) |