Why doesn't recharts have a heatmap out of the box?

recharts focuses on cartesian and polar series. A heatmap is a grid of coloured cells rather than a series, so Vireya builds it from SVG primitives inside the same ChartContainer, keeping tokens and tooltips consistent with the rest of the library.

What colour scale should a heatmap use?

Use a sequential scale (light to dark in one hue) for magnitude, and a diverging scale (two hues meeting at a neutral midpoint) for signed data such as a -1..1 correlation matrix.

Can I show the exact numbers in a heatmap?

Yes. Vireya's correlation variant renders values inside each cell with automatically contrasting text, so the grid reads both as a pattern and as exact figures.

All charts

heatmap/*

Heatmap

Heatmaps — density / activity over a 2D grid. Composed from SVG primitives wrapped in ChartContainer (recharts has no native heatmap).

2 variants

@vireya/ui/charts/heatmap/calendar

GitHub-style 53×7 calendar heatmap. SVG grid + color-mix intensity off the active accent token, with native <title> tooltips.

client

@vireya/ui/charts/heatmap/correlation

Symmetric correlation matrix with a diverging color scale (-1..1) and the HeatmapCellLabels primitive rendering values inside cells with auto-contrast text.

client

Understanding Heatmap charts

A heatmap maps values onto a 2D grid and encodes each cell with colour intensity, letting you spot patterns, clusters and outliers across two dimensions at once — activity by day-of-week and hour, or correlations across many variables.

recharts has no native heatmap, so Vireya composes one from SVG primitives inside its ChartContainer, deriving cell colour from your accent token via color-mix with native title tooltips.

When to use

Activity or density across two categorical axes (calendar heatmaps, cohort grids).
Correlation matrices across many numeric variables.
Spotting hotspots and gaps in a large but structured dataset.

When to avoid

Precise value reading — colour encodes magnitude only approximately.
Few data points, where a bar or table is clearer.
Sequential trends better served by a line chart.

Best practices

Choose a sequential scale for magnitude and a diverging scale for signed data like correlation.
Print values inside cells when precision matters and space allows.
Keep the scale perceptually uniform so equal steps look equal.
Give cells a subtle gap or border so the grid structure reads.

Accessibility

Provide a legend mapping colour to value range.
Use auto-contrast text labels inside cells where exact values matter.
Offer the data as a table for users who can't perceive the colour encoding.

Frequently asked questions

Why doesn't recharts have a heatmap out of the box?: recharts focuses on cartesian and polar series. A heatmap is a grid of coloured cells rather than a series, so Vireya builds it from SVG primitives inside the same ChartContainer, keeping tokens and tooltips consistent with the rest of the library.
What colour scale should a heatmap use?: Use a sequential scale (light to dark in one hue) for magnitude, and a diverging scale (two hues meeting at a neutral midpoint) for signed data such as a -1..1 correlation matrix.
Can I show the exact numbers in a heatmap?: Yes. Vireya's correlation variant renders values inside each cell with automatically contrasting text, so the grid reads both as a pattern and as exact figures.