# Heatmap

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-605bfa2f83c8b65276450eb668214968fe72685a%2Fillustration_heatmap_NEW.png?alt=media" alt=""><figcaption></figcaption></figure>

## 🧭 Overview

A heatmap is a graphical representation of data where individual values are represented by color. It helps users quickly identify patterns, correlations, and outliers across two categorical dimensions (X and Y axes). Heatmaps are particularly useful when analyzing dense datasets or when you want to present values in a visually compact and intuitive format.

> 📊 Example Use Case
>
> * Comparing user engagement levels across different features and time periods
> * Analyzing performance metrics across departments and teams
> * Tracking bug frequencies by category and priority level
> * Visualizing correlation matrices for statistical analysis
> * Monitoring server load across regions and time intervals

***

## ⭐ Key Features

* **Add secondary cell value:** Go beyond just visualizing numbers—add a complementary value to each cell to provide deeper context. Whether it’s displaying percentage change, confidence intervals, or notes, this feature helps users interpret the data more accurately and make informed decisions faster.The heatmap helps you acquire a global vision on combining several indicators and entities. It is also ideal for cutting through data.

## Configuration

{% tabs %}
{% tab title="New Heatmap" %}
**Learn how to create a heatmap using the new design with this step-by-step guide.**\
Explore the interactive walkthrough below to get started quickly, then dive into the full configuration reference table for in-depth details.

{% @arcade/embed url="<https://app.arcade.software/share/UCVPJ7LIhosiWMYMBWNI>" flowId="UCVPJ7LIhosiWMYMBWNI" %}

**Chart Configuration Step-by-Step**

|                           | Option                   | How does it work?                                                                                                                                                                                                                                                                                                                       |
| ------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dimension**             |                          |                                                                                                                                                                                                                                                                                                                                         |
|                           | Column X-Axis            | Select the data column to be displayed on the X-axis (horizontal).                                                                                                                                                                                                                                                                      |
|                           | Order columns            | Define sort order for X-axis values (column based or custom).                                                                                                                                                                                                                                                                           |
|                           | Reverse column order     | Invert the order of X-axis labels.                                                                                                                                                                                                                                                                                                      |
| **Measure**               |                          |                                                                                                                                                                                                                                                                                                                                         |
|                           | Row Y-Axis               | Select the data column to be displayed on the Y-axis (vertical).                                                                                                                                                                                                                                                                        |
|                           | Primary cell value       | Specify the main value to be visualized via color intensity.                                                                                                                                                                                                                                                                            |
|                           | Precision                | <p>Precision determines the level of detail in how your values are displayed. By default, measures use a <code>.2f</code> format, meaning they are shown with two decimal places.</p><p><strong>Example:</strong><br>A value of <code>3.14159</code> will be displayed as <code>3.14</code> when using <code>.2f</code> formatting.</p> |
|                           | Unit                     | Unit represents the total quantity or category being measured for a KPI. It defines what the values correspond to, providing context for better interpretation.                                                                                                                                                                         |
|                           | Sentiment                | <p>Four different sentiment statuses (positive, warning, negative, neutral) can be used to color bars, enhancing visual distinction.</p><p><em>Note: Sentiments can be customized in the app theme.</em></p>                                                                                                                            |
|                           | Add secondary cell value | Include an optional second value (e.g. shown on hover or as a label).                                                                                                                                                                                                                                                                   |
|                           | Order rows               | Define sort order for Y-axis values (column based or custom).                                                                                                                                                                                                                                                                           |
|                           | Reverse row order        | Invert the order of Y-axis labels.                                                                                                                                                                                                                                                                                                      |
| **Additional parameters** |                          |                                                                                                                                                                                                                                                                                                                                         |
|                           | ID                       | Unique chart Id                                                                                                                                                                                                                                                                                                                         |
|                           | Add complementary value  | The complementary value is displayed in the data label, providing additional context and making it easier for viewers to interpret the data at a glance. It is possible to add a precision, an unit and a sentiment.                                                                                                                    |
|                           | Add user chart guide     | Lead your chart viewers through the narrative of your data.                                                                                                                                                                                                                                                                             |
| **Chart performance**     |                          | Technical performance                                                                                                                                                                                                                                                                                                                   |

**Style Configuration**

|              | Option      | How does it work?                                                |
| ------------ | ----------- | ---------------------------------------------------------------- |
|              | Cell height | Sets the vertical size of each cell in pixels. Default: 60 px.   |
|              | Cell width  | Sets the horizontal size of each cell in pixels. Default: 60 px. |
| {% endtab %} |             |                                                                  |

{% tab title="Legacy Heatmap" %}
This page provides a step-by-step guide for creating a barchart using the legacy design.

<mark style="color:red;">\*</mark>**Mandatory parameters**

| Section      | Option                                             | Configuration tutorial                                                                                                                                                                        |
| ------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|              | Dataset<mark style="color:red;">\*</mark>          | Select the dataset used by the chart                                                                                                                                                          |
|              | X axis (columns)<mark style="color:red;">\*</mark> | Select the column corresponding to the abscissa                                                                                                                                               |
|              | Y axis (rows)<mark style="color:red;">\*</mark>    | Select the column corresponding to the ordinate                                                                                                                                               |
|              | Value<mark style="color:red;">\*</mark>            | Select the aggregation to use, and the column on which the aggregation will be applied for you value (Intersection of your breakdowns)                                                        |
| Legend       | Display legend                                     | Click on the toogle to use legend                                                                                                                                                             |
| Legend       | Default selection -> Default selected column       | <p>(The display legend option should be activated for this one)</p><p>Check the box "Default selection", then "Default selected column"<br>Select the configuration type</p>                  |
| Legend       | Default selection -> Default selected row          | <p>(The display legend option should be activated for this one)</p><p>Check the box "Default selection", then "Default selected row"<br>Select the configuration type</p>                     |
| Legend       | Additional info                                    | <p>(The display legend option should be activated for this one)</p><p>Check the box "Additional info"<br>Select a column and an aggregation for additional infos to display in the legend</p> |
| Legend       | Select intersection on hover                       | <p>(The display legend option should be activated for this one)<br>Click on the toogle to activate this option</p>                                                                            |
| Sort         | X order                                            | <p>(By default, alphabetical order)<br>Check the box "X order"<br>Select the configuration type and the Order (column to use for ordering)</p>                                                |
| Sort         | Y order                                            | <p>(By default, alphabetical order)<br>Check the box "Y order"<br>Select the configuration type and the Order (column to use for ordering)</p>                                                |
| Packs        | X Packs                                            | Check the box "X Packs" and select the column containing informations about grouping label                                                                                                    |
| Packs        | Y Packs                                            | Check the box "Y Packs" and select the column containing informations about grouping label                                                                                                    |
| Packs        | Display Pack names                                 | Click on the toggle "Display pack names"                                                                                                                                                      |
| Packs        | X packs order                                      | <p>(By default, alphabetical order)</p><p>Check the box<br>Select the configuration type<br>Select the column to use for ordering</p>                                                         |
| Packs        | Y packs order                                      | <p>(By default, alphabetical order)</p><p>Check the box<br>Select the configuration type<br>Select the column to use for ordering</p>                                                         |
| Enrich chart | Second value                                       | <p>Check the box.<br>Select the column to display as second value, and the aggregation.</p>                                                                                                   |
| Enrich chart | Target                                             | <p>(The target value will be displayed only in the Legend)<br>Check the box "Target" and select the column corresponding the the target</p>                                                   |
| Display      | Display all values and subvalues                   | Check the box                                                                                                                                                                                 |
| Display      | Square's transparency                              | <p>Check the box<br>Select the column to be based on to determine transparency level</p>                                                                                                      |
| Display      | Square height (in pixels)                          | Enter the square height in pixels (caped at 40px on mobile)                                                                                                                                   |
| Display      | Square width (in pixels)                           | Enter the square width in pixels (caped at 40px on mobile)                                                                                                                                    |
| Display      | Y Label width (in pixels)                          | Enter the square width in pixels (caped at 100px on mobile)                                                                                                                                   |
| Display      | Display Y axis dots                                | Click on the toogle in order to display dots between the label and squares                                                                                                                    |
| Display      | Size                                               | <p>(Used only for multiple charts)</p><p>Enter a proportion of the total screen between 0 and 1</p>                                                                                           |
| Display      | Mobile size                                        | <p>(Used only for multiple charts)</p><p>Enter a proportion of the total screen between 0 and 1 for mobile screens</p>                                                                        |
| Display      | Custom CSS class                                   | Set a custom CSS class to target this specific chart with CSS                                                                                                                                 |
| Tutorial     | ID                                                 | <p>Enter an ID.</p><p>Change the ID to display the tutorial again.</p><p>All tutorials with the same ID will be displayed only once.</p>                                                      |
| Tutorial     | Message                                            | <p>Enter your message.<br>This will be displayed to your users</p>                                                                                                                            |
| Tutorial     | Always show this tutorial                          | By default the tutorial is shown once only                                                                                                                                                    |
| {% endtab %} |                                                    |                                                                                                                                                                                               |

{% tab title="New vs. Legacy Configuration" %}

| **⭐️ New**               | **Legacy**       |
| ------------------------ | ---------------- |
| **Column X-Axis**        | X axis (columns) |
| Order columns            | X order          |
| Reverse column order     | /                |
| **Row Y-Axis**           | Y axis (rows)    |
| Primary cell value       | Value            |
| Add secondary cell value | Cell value       |
| Order rows               | Order            |
| Reverse row order        | /                |
| Add complementary value  | Additional info  |
| Add user chart guide     | Tutorial         |
| {% endtab %}             |                  |
| {% endtabs %}            |                  |