# Heatmap Chart

Source: https://lumeo.nativ.sh/components/charts/heatmap

# Heatmap Chart

Display density or intensity across two dimensions using color gradients. Useful for activity patterns, correlation matrices, and time-based analysis.

## Installation

.NET CLI PackageReference Lumeo CLI

dotnet add package Lumeo.Charts

One-time app setup (`AddLumeo()`, CSS & JS) is covered in the [installation guide](docs/introduction).

## Usage

@using Lumeo

<HeatmapChart />

Preview Code

Activity Heatmap

Support ticket volume by day of week and time of day. Darker cells indicate peak load periods, helping teams plan staffing accordingly.

Preview Code

Sales by Region & Month

Monthly revenue heatmap across four regions. Custom warm color range maps low-to-high values from cream to deep red.

Preview Code

Server Error Rate Matrix

Error rate per hour slot and weekday. Data labels always visible; DataZoom and Toolbox enabled for deeper exploration.

Preview Code

Feature Adoption Matrix

Feature usage rate (%) for seven user segments across five key features. A green-to-violet scale highlights low-adoption gaps.

Preview Code

Loading state

Simulate loading

Hold skeleton open

Duration: 2s 

Cycle: 1400 ms 

Shape-aware skeleton with reserved space for legend and axes — no layout shift when real data arrives.

## API Reference

### HeatmapChart

Property

Type

Default

Description

XCategories

List<string>

\[\]

X-axis category labels.

YCategories

List<string>

\[\]

Y-axis category labels.

Data

List<double\[\]>

\[\]

Data points as \[x, y, value\] arrays.

Colors

List<string>?

null

Custom color range for the visual map.

IsLoading

bool

false

When true, renders a shape-matched loading skeleton in place of the chart. Bind to your async fetch state.

ShowLoadingSkeleton

bool

true

Set to false to opt out of the skeleton (chart area stays empty while IsLoading is true).

SkeletonKind

ChartSkeletonKind

(chart default)

Override the skeleton silhouette (Bars, Line, Area, Pie, Scatter, Grid, Generic).

SkeletonStyle

ChartSkeletonStyle

Phantom

Phantom renders the real chart with placeholder data and morphs to real data via ECharts animation. Silhouette falls back to the legacy SVG skeleton overlay.

ShowLoadingLabel

bool

true

Shows a small "Loading…" pill in the top-right corner whenever `IsLoading` is true. Layered on top of any `SkeletonStyle`. Set to false for bare visuals. **(rc.18)**

LoadingText

string?

"Loading…"

Label rendered next to the spinner inside the loading pill. Set to empty to show the spinner alone. **(rc.18)**

ShowLegend

bool

true

Toggles the visual-map legend that explains the heatmap color scale.

ShowTooltip

bool

true

Shows the per-cell tooltip on hover with x/y categories and value.

Width

string

"100%"

CSS width applied to the chart container.

Height

string

"350px"

CSS height applied to the chart container.

Theme

string?

null

Overrides the ECharts theme; null follows the app's light/dark mode.

ShowDataLabels

bool

false

Renders the numeric value inside each heatmap cell.

LabelPosition

string

"inside"

Position of cell data labels (e.g. inside, top, bottom).

LabelFormat

string?

null

ECharts format string applied to cell data labels.

DataZoom

bool

false

Enables zoom/pan controls along the heatmap axes.

Toolbox

bool

false

Shows the toolbox with save-as-image, restore, and view controls.

ColorPalette

List<string>?

null

Overrides the chart's base color palette; alternative to per-cell Colors gradient.

AnimationDuration

int?

null

Override entry animation duration (ms); null uses the ECharts default.

AnimationEasing

string?

null

ECharts easing function name applied to entry animations.

PhantomCycleMs

int

1400

Phantom-mode refresh interval in milliseconds. Lower = faster data cycling while loading.

MarkLine

EChartMarkLine?

null

Optional mark line(s) overlaid on the heatmap grid.

MarkPoint

EChartMarkPoint?

null

Optional mark point annotations overlaid on the heatmap.

MarkArea

EChartMarkArea?

null

Optional mark area highlight overlaid on the heatmap grid.