> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/build/charts/chart-types/heatmap-chart.md).

# Heatmap chart

{% hint style="info" %}
**Target Audience**: Non-technical users and builders configuring charts in the Library.
{% endhint %}

<figure><img src="/files/0PgUcG0PaKc3SOEowF7L" alt="Heatmap example"><figcaption></figcaption></figure>

## Overview

A heatmap shows a **primary cell value** for each pair of categories: one on **Columns (X-Axis)** and one on **Rows (Y-Axis)**. Color intensity reflects the metric. You can add a **secondary cell value** per cell.

* **Dimension:** **Columns (X-Axis)**.
* **Measure:** **Rows (Y-Axis)**, **Primary cell value**, and optional **Secondary cell value**.

In the **Library**, enable **Manual Edit**, set **Type** to **Heatmap**, and map columns under **Data**.

Shared fields (**Title**, **Narrative**, **Data**) are in [Chart types](/build/charts/chart-types.md#shared-chart-level-settings).

## When to use it

**Good fit**

* Compare a metric across **two categorical dimensions** (region × product, day × hour).
* Spot patterns or hotspots in a grid.
* Show a main metric plus a second number per cell.

**Prefer another chart**

* One dimension + trend → [Line chart](/build/charts/chart-types/line-chart.md).
* Category comparison without a grid → [Bar chart](/build/charts/chart-types/bar-chart.md).
* Detailed row-level data → [Table](/build/charts/chart-types/table.md).

**Examples:** activity by weekday and hour, sales by region and category, errors by service and severity.

**Common setups**

* **Two categories:** **Columns (X-Axis)** + **Rows (Y-Axis)** + **Primary cell value** (e.g. Sum).
* **Two metrics per cell:** enable **Add secondary cell value** and set **Secondary cell value**.

## Configuration options

Open the chart in the **Library**, turn on **Manual Edit**, select **Data**, then set **Type** to **Heatmap**. Panel **Dimension** holds the X axis; panel **Measure** holds rows, primary value, and *More measure options*.

Prerequisites: [connected database](/build/data-connections/how-to/add-a-database.md), Manual Edit ([how-to](/build/charts/how-to/customize-a-chart-manually.md)).

### Dimension

| Option               | How it works                                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Columns (X-Axis)** | Horizontal categories.                                                                                         |
| **Date granularity** | Only shown when **Columns (X-Axis)** is a date column. **Year**, **Quarter**, **Month**, **Week**, or **Day**. |
| **Date format**      | Only shown when **Columns (X-Axis)** is a date column. How dates appear on the X axis.                         |

### Measure

| Option                   | How it works                                                                                                               |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **Rows (Y-Axis)**        | Vertical categories (shown in the Measure panel).                                                                          |
| **Date granularity**     | Only shown when **Rows (Y-Axis)** is a date column. **Year**, **Quarter**, **Month**, **Week**, or **Day**.                |
| **Date format**          | Only shown when **Rows (Y-Axis)** is a date column. How dates appear on the Y axis.                                        |
| **Primary cell value**   | Metric driving cell color. Often numeric; use **Aggregation** as needed.                                                   |
| **Aggregation**          | On **Primary cell value** after the column is selected.                                                                    |
| **Format number**        | Shown when the primary value is numeric (after aggregation).                                                               |
| **Secondary cell value** | *More measure options.* Shown when the secondary metric toggle is enabled. Same aggregation/format options as the primary. |

The AI assistant can pre-fill axes and metrics; use **Manual Edit** to adjust.