# Heatmap

> Heatmap (MUI X Pro) demos: activity grids, a correlation matrix, continuous and piecewise color scales, custom cell styling and click interaction.

**Site index:** [https://muicharts.2plot.dev/llms.txt](https://muicharts.2plot.dev/llms.txt) — every page on this site, as Markdown.  
**Network index:** [https://2plot.dev/llms.txt](https://2plot.dev/llms.txt) — The 2plot network; start here to discover sibling sites.  
**Sibling sites:** 13 more in The 2plot network — listed in the site index above.  
**Sitemap:** https://muicharts.2plot.dev/sitemap.xml  


---



### Overview

`Heatmap` renders matrix/grid visualizations with color-coded cells,
wrapping the MUI X Charts Pro heatmap for Plotly Dash.

Cells are addressed by x/y index against categorical axis labels, and each
cell's color is derived from its value through a color scale (continuous
or piecewise). Cell clicks flow back to Dash as `clickData` with x, y, and
value.


    Heatmap is a **MUI X Pro** component — a Pro license key is required,
    passed via the `licenseKey` prop. These demos read it from the
    `MUI_PRO_API_KEY` environment variable; without it the charts render
    with the unlicensed watermark.

```python
# Data format: [x_index, y_index, value] triples
from dash_mui_charts import Heatmap

Heatmap(
    id='my-heatmap',
    licenseKey=MUI_LICENSE_KEY,
    data=[[0, 0, 10], [0, 1, 20], [1, 0, 40], [1, 1, 50]],
    xAxis={'data': ['Mon', 'Tue'], 'label': 'Day'},
    yAxis={'data': ['Week 1', 'Week 2'], 'label': 'Week'},
    height=300,
    colorScale={
        'type': 'continuous',
        'min': 0,
        'max': 100,
        'colors': ['#e3f2fd', '#1976d2'],
    },
)
```

---

### Basic heatmap

A simple heatmap showing weekly activity levels. Data is provided as
`[x_index, y_index, value]` tuples.



```python
# File: docs/heatmap/basic_example.py

import os

from dash import html

from dash_mui_charts import Heatmap
from docs.heatmap._data import activity_data, days, weeks

MUI_LICENSE_KEY = os.environ.get('MUI_PRO_API_KEY', '')

component = html.Div(
    [
        # The Pro degradation banner: rendered only when no license key is
        # configured, so a keyless deployment says WHY the charts carry the
        # unlicensed watermark. tests/test_pages_smoke.py asserts this.
        html.Div(
            html.P(
                "This feature requires an MUI X Pro license key. "
                "Set your license key in the MUI_PRO_API_KEY environment "
                "variable.",
                style={
                    'backgroundColor': '#fff3e0',
                    'padding': '12px 16px',
                    'borderRadius': '4px',
                    'borderLeft': '4px solid #ff9800',
                    'marginBottom': '20px',
                },
            )
        ) if not MUI_LICENSE_KEY else None,
        Heatmap(
            id='basic-heatmap',
            licenseKey=MUI_LICENSE_KEY,
            data=activity_data,
            xAxis={'data': days, 'label': 'Day of Week'},
            yAxis={'data': weeks, 'label': 'Week'},
            height=300,
            colorScale={
                'type': 'continuous',
                'min': 0,
                'max': 10,
                'colors': ['#e3f2fd', '#1565c0'],
            },
        ),
    ]
)
```

    :defaultExpanded: false
    :withExpandedButton: true

---

### Correlation matrix

Heatmaps are ideal for displaying correlation matrices. Use a diverging
color scale to show positive and negative correlations.



```python
# File: docs/heatmap/correlation_example.py

import os

from dash_mui_charts import Heatmap
from docs.heatmap._data import correlation_data, variables

MUI_LICENSE_KEY = os.environ.get('MUI_PRO_API_KEY', '')

# Correlation values range from -1 to 1 — a diverging red-white-blue scale.
component = Heatmap(
    id='correlation-heatmap',
    licenseKey=MUI_LICENSE_KEY,
    data=correlation_data,
    xAxis={'data': variables},
    yAxis={'data': variables},
    height=400,
    colorScale={
        'type': 'continuous',
        'min': -1,
        'max': 1,
        'colors': ['#d32f2f', '#fff', '#1976d2'],  # Red to White to Blue
    },
    margin={'left': 100, 'right': 20, 'top': 20, 'bottom': 80},
)
```

    :defaultExpanded: false
    :withExpandedButton: true

---

### Temperature heatmap

A practical example showing hourly temperatures across the week, with a
warm color scale from cool (blue) to hot (red).



```python
# File: docs/heatmap/temperature_example.py

import os

from dash_mui_charts import Heatmap
from docs.heatmap._data import hours, temp_days, temperature_data

MUI_LICENSE_KEY = os.environ.get('MUI_PRO_API_KEY', '')

component = Heatmap(
    id='temperature-heatmap',
    licenseKey=MUI_LICENSE_KEY,
    data=temperature_data,
    xAxis={'data': temp_days, 'label': 'Day'},
    yAxis={'data': hours, 'label': 'Time'},
    height=350,
    colorScale={
        'type': 'continuous',
        'min': 50,
        'max': 90,
        'colors': ['#42a5f5', '#ffeb3b', '#f44336'],  # Blue-Yellow-Red
    },
)
```

    :defaultExpanded: false
    :withExpandedButton: true

---

### Custom rounded cells

Use `cellStyle='rounded'` for cells with gaps, rounded corners, and value
labels.



```python
# File: docs/heatmap/rounded_example.py

import os

from dash_mui_charts import Heatmap
from docs.heatmap._data import activity_data, days, weeks

MUI_LICENSE_KEY = os.environ.get('MUI_PRO_API_KEY', '')

component = Heatmap(
    id='rounded-heatmap',
    licenseKey=MUI_LICENSE_KEY,
    data=activity_data,
    xAxis={'data': days, 'label': 'Day of Week'},
    yAxis={'data': weeks, 'label': 'Week'},
    height=300,
    colorScale={
        'type': 'continuous',
        'min': 0,
        'max': 10,
        'colors': ['#e8f5e9', '#2e7d32'],
    },
    cellStyle='rounded',  # Enable rounded corners with gap
    highlightScope={'highlight': 'item'},  # Highlight on hover
)
```

    :defaultExpanded: false
    :withExpandedButton: true

---

### Custom cell configuration

Fine-tune cell appearance with custom gap, border radius, font size, and
colors.



```python
# File: docs/heatmap/custom_cells_example.py

import os

from dash_mui_charts import Heatmap
from docs.heatmap._data import activity_data, days, weeks

MUI_LICENSE_KEY = os.environ.get('MUI_PRO_API_KEY', '')

component = Heatmap(
    id='custom-cell-heatmap',
    licenseKey=MUI_LICENSE_KEY,
    data=activity_data,
    xAxis={'data': days},
    yAxis={'data': weeks},
    height=300,
    colorScale={
        'type': 'continuous',
        'min': 0,
        'max': 10,
        'colors': ['#fce4ec', '#c2185b'],  # Pink gradient
    },
    cellStyle={
        'gap': 6,               # Space between cells
        'borderRadius': 8,      # Rounded corners
        'showValue': True,      # Display value in cell
        'fontSize': 14,         # Text size
        'fontWeight': 600,      # Text weight
        'textColor': '#ffffff',  # Text color
    },
    highlightScope={'highlight': 'item'},
)
```

    :defaultExpanded: false
    :withExpandedButton: true

---

### Piecewise color scale

Use a piecewise color scale for discrete color bands — useful for
categorizing values into ranges (Low, Medium, High).



```python
# File: docs/heatmap/piecewise_example.py

import os

from dash import html

from dash_mui_charts import Heatmap
from docs.heatmap._data import activity_data, days, weeks

MUI_LICENSE_KEY = os.environ.get('MUI_PRO_API_KEY', '')

component = html.Div(
    [
        Heatmap(
            id='piecewise-heatmap',
            licenseKey=MUI_LICENSE_KEY,
            data=activity_data,
            xAxis={'data': days},
            yAxis={'data': weeks},
            height=300,
            colorScale={
                'type': 'piecewise',
                'thresholds': [3, 5, 7],  # Creates 4 color bands
                'colors': ['#e8f5e9', '#81c784', '#43a047', '#1b5e20'],
            },
        ),
        html.Div(
            [
                html.Span("Legend: ", style={'fontWeight': 'bold',
                                             'marginRight': '10px'}),
                html.Span("0-2 (Low) ",
                          style={'backgroundColor': '#e8f5e9',
                                 'padding': '2px 8px', 'marginRight': '5px'}),
                html.Span("3-4 ",
                          style={'backgroundColor': '#81c784',
                                 'padding': '2px 8px', 'marginRight': '5px'}),
                html.Span("5-6 ",
                          style={'backgroundColor': '#43a047',
                                 'padding': '2px 8px', 'marginRight': '5px',
                                 'color': 'white'}),
                html.Span("7+ (High)",
                          style={'backgroundColor': '#1b5e20',
                                 'padding': '2px 8px', 'color': 'white'}),
            ],
            style={'marginTop': '15px'},
        ),
    ]
)
```

    :defaultExpanded: false
    :withExpandedButton: true

---

### Interactive heatmap

Click on cells to see their data — the heatmap reports click events with
x, y coordinates and value.



```python
# File: docs/heatmap/interactive_example.py

import json
import os

from dash import Input, Output, callback, html

from dash_mui_charts import Heatmap
from docs.heatmap._data import activity_data, days, weeks

MUI_LICENSE_KEY = os.environ.get('MUI_PRO_API_KEY', '')

component = html.Div(
    [
        Heatmap(
            id='interactive-heatmap',
            licenseKey=MUI_LICENSE_KEY,
            data=activity_data,
            xAxis={'data': days, 'label': 'Day'},
            yAxis={'data': weeks, 'label': 'Week'},
            height=300,
            colorScale={
                'type': 'continuous',
                'min': 0,
                'max': 10,
                'colors': ['#fff3e0', '#ff9800'],
            },
        ),
        html.H4("Click Data:", style={'marginTop': '20px'}),
        html.Pre(
            id='heatmap-click-output',
            children="Click on a cell to see its data",
            style={
                'backgroundColor': '#f5f5f5',
                'padding': '15px',
                'borderRadius': '5px',
                'whiteSpace': 'pre-wrap',
                'fontSize': '12px',
                'overflow': 'auto',
            },
        ),
    ]
)


@callback(
    Output('heatmap-click-output', 'children'),
    Input('interactive-heatmap', 'clickData'),
    prevent_initial_call=True
)
def display_click(click_data):
    """Display clicked cell data from heatmap."""
    if click_data:
        return json.dumps(click_data, indent=2)
    return "Click on a cell to see its data"
```

    :defaultExpanded: false
    :withExpandedButton: true

---

### Color scale reference

| Type | Configuration | Use case |
|------|---------------|----------|
| Continuous | `{'type': 'continuous', 'min': 0, 'max': 100, 'colors': ['#low', '#high']}` | Smooth gradient for numerical data |
| Diverging | `{'type': 'continuous', 'min': -1, 'max': 1, 'colors': ['#neg', '#mid', '#pos']}` | Correlations, deviations from center |
| Piecewise | `{'type': 'piecewise', 'thresholds': [a, b, c], 'colors': ['#1', '#2', '#3', '#4']}` | Categorical ranges (Low/Med/High) |

Piecewise thresholds `[3, 5, 7]` create four bands (0–2, 3–4, 5–6, 7+) and
need `len(thresholds) + 1` colors.

---

### Related pages

- [Props Explorer](/heatmap-props) — interactive props playground with live controls


---

*Source: /heatmap*