Charts - Heatmap

#Usage

import { ChartAnnotation, ChartCanvas, ChartCaption, ChartColorLegend, ChartExportMenu, ChartHeatmap, ChartHover, ChartItem, ChartSvg, ChartTitle, ChartTooltip, ChartXAxis, ChartYAxis } from '@primeui/vue-chart';

<ChartSvg>
    <ChartHeatmap :data="data" category-x-field="categoryXField" category-y-field="categoryYField" value-field="valueField" />
    <ChartXAxis />
    <ChartYAxis />
</ChartSvg>

Heatmaps encode value intensity as color across a two-dimensional categorical grid. Each cell maps a column, row, and value. Add ChartColorLegend to display the color scale.

#Basic

Set categoryXField, categoryYField, and valueField to map data fields to the two categorical axes and the color intensity. The demo maps support ticket intake by weekday and queue window, then adds ChartXAxis and ChartYAxis for category labels.

#Color Range

Set colorRange to define a multi-stop color gradient. Values interpolate between the data minimum and maximum. Set colorScale alongside colorRange to define explicit breakpoints instead of auto-computing them, which is necessary for diverging scales where zero needs to map to a specific stop. Use min and max to override the color mapping domain.

#Single Color

Pass a single color (a solid, gradient, or pattern) instead of colorRange to use opacity-based mapping. Cell opacity scales from the minimum to the maximum value, with no hue change across the range; this works best for positive measures such as feature adoption.

#Cell Styling

Cells tile the plot area edge to edge, so spacing is the only thing that separates them: it insets each cell by that many pixels on all four sides, giving an even gap between neighbours and the same inset at the grid's outer edge. Set borderRadius for rounded corners. Use borderColor and borderStrokeWidth to add a border around each cell. Set nullColor to customize the fill for missing data cells and showEmptyCells to hide them entirely.

#Custom Content

Set renderContent to draw custom content inside each cell. The callback receives the cell's position, dimensions, value, resolved color, and row/column labels. In SVG mode return a VNode. In Canvas mode the context is pre-clipped to the cell bounds. Draw directly and return null.

#Declarative

Define cells inline using ChartItem children instead of a data array. Each ChartItem accepts category-x for the X axis category, category-y for the Y axis category, and value for the cell intensity.

#Title & Caption

Add ChartTitle to display a title above the chart and ChartCaption for a descriptive line beneath it. Both reduce the chart area height together.

For full configuration see Title & Caption.

#Hover

Add ChartHover to apply visual feedback on hover. By default the hovered cell brightens and the other cells stay unchanged. Set dimOpacity on ChartHover to fade the non-hovered cells instead.

For full configuration see Hover.

#Tooltip

Add ChartTooltip to show cell details on hover. The tooltip displays the X category, Y category, and value for the hovered cell. Cells tile the plot, so the cursor always resolves to one: the gap left by spacing belongs to the cell beside it rather than reporting nothing, which keeps the tooltip steady while moving across a dense grid. Set snap="none" on the tooltip to hover only the painted cell and leave the gaps empty.

For full configuration see Tooltip.

#Legend

Add ChartColorLegend to display a continuous gradient bar that maps values to colors. Set position to top, bottom, left, or right. Use ticks to control the number of labels and formatLabel to customize their text. Set steps to render discrete color blocks instead of a gradient.

For full configuration see Legend.

#Axes

Use ChartXAxis and ChartYAxis to render category labels along each axis. Set label on each axis to add axis titles.

For full configuration see Axes.

#Data Labels

Add ChartDataLabels to display a value inside each cell. Use formatter to customize the text. Set display to value, percentage, or both, where the percentage is each cell's share of the non-empty total. Percentage is meaningful for additive data such as counts or sales, not for correlations or temperatures. Labels use dark text on light cells and light text on dark cells by default; override with color, which can be a callback receiving fillColor to compute a custom contrast. Cells auto-size the text and hide labels that do not fit.

For full configuration see Data Labels.

#Annotation

Use ChartAnnotation to render custom content overlaid on the chart area. The render callback receives chartArea, center, xScale, yScale, textColor, isDark, and ctx (Canvas mode only). Use xScale and yScale to position annotations at specific cell coordinates. Use getScale to look up axes by ID. In SVG mode return a VNode. In Canvas mode draw to ctx and return null.

For full configuration see Annotation.

#Animation

Pass the chart-root animation prop (<ChartSvg> / <ChartCanvas>) to control entrance and update transitions. Cells fade in on entrance and cross-fade to new colors on data updates.

For full configuration see Animation.

#Export

Add ChartExportMenu to let users download the chart as PNG, SVG, or PDF.

See Export for format options and programmatic export.

#Responsive

See Responsive for container sizing, aspect ratio, and breakpoint configuration.

#Accessibility

See Accessibility for ARIA labels, keyboard navigation, and screen reader support.

#API

#ChartHeatmap

Visual styling props with type accessor → R accept a static value, a per-cell array, a field name (keyof T), or a callback (ctx: ItemContext<T>) => R | undefined. Color-family arrays cycle modulo length; other accessor arrays clip and fall back to the series default.

#ItemContext

Passed to every accessor → R callback. Return undefined to fall back to the series-level default for that cell.

#Color Resolution Priority

Colors are resolved in this order. The first matching rule wins:

#HeatmapCellContext

Passed to the renderContent callback for each cell.

#ChartItem

Use ChartItem as children of ChartHeatmap instead of a data array for inline cell definitions.

#Related Docs

• Heatmap Examples
• Legend
• Tooltip
• Hover
• Annotation
• Animation
• Axes
• Data Labels