import { Heatmap } from "semiotic"
Heatmap visualizes matrix data with color-encoded cells. It is ideal for showing patterns, correlations, and distributions across two categorical or ordinal dimensions. The color intensity of each cell encodes a continuous value, making it easy to spot clusters and outliers at a glance.
Quick Start
A heatmap requires data with x, y, and value fields. The default accessors match "x", "y", and"value".
import { Heatmap } from "semiotic" const frameProps = { /* --- Data --- */ data: [ { day: 1, hour: 8, value: 12 }, { day: 1, hour: 10, value: 25 }, { day: 1, hour: 12, value: 42 }, // ...more data points ], /* --- Process --- */ xAccessor: "day", yAccessor: "hour", valueAccessor: "value", /* --- Customize --- */ xLabel: "Day", yLabel: "Hour" } export default () => { return <Heatmap {...frameProps} /> }
Examples
With Cell Value Labels
Set showValues to true to display numeric labels inside each cell.
import { Heatmap } from "semiotic" const frameProps = { /* --- Data --- */ data: [ { x: 1, y: 1, value: 1.0 }, { x: 1, y: 2, value: 0.8 }, // ...correlation matrix data ], /* --- Process --- */ xAccessor: "x", yAccessor: "y", valueAccessor: "value", /* --- Customize --- */ xLabel: "Variable", yLabel: "Variable", showValues: true, valueFormat: d => d.toFixed(1) } export default () => { return <Heatmap {...frameProps} /> }
Color Schemes
Choose from built-in color schemes: "blues","reds", "greens", or "viridis".
import { Heatmap } from "semiotic" const frameProps = { /* --- Data --- */ data: activityData, /* --- Process --- */ xAccessor: "day", yAccessor: "hour", valueAccessor: "value", /* --- Customize --- */ xLabel: "Day", yLabel: "Hour", colorScheme: "viridis" } export default () => { return <Heatmap {...frameProps} /> }
Custom Cell Borders
Adjust cellBorderColor and cellBorderWidth to change the appearance of cell boundaries.
import { Heatmap } from "semiotic" const frameProps = { /* --- Data --- */ data: activityData, /* --- Process --- */ xAccessor: "day", yAccessor: "hour", valueAccessor: "value", /* --- Customize --- */ xLabel: "Day", yLabel: "Hour", colorScheme: "reds", cellBorderColor: "#333", cellBorderWidth: 2 } export default () => { return <Heatmap {...frameProps} /> }
Gradient Legend
Set showLegend to display a gradient color legend that represents the continuous value scale. Use legendPosition to control where the legend appears relative to the chart.
import { Heatmap } from "semiotic" const frameProps = { /* --- Data --- */ data: activityData, /* --- Process --- */ xAccessor: "day", yAccessor: "hour", valueAccessor: "value", /* --- Customize --- */ xLabel: "Day", yLabel: "Hour", colorScheme: "viridis", showLegend: true, legendPosition: "right" } export default () => { return <Heatmap {...frameProps} /> }
Props
| Prop | Type | Required | Default | Description |
|---|
data | array | Yes | — | Array of data points with x, y, and value properties. |
xAccessor | string | function | — | "x" | Field name or function to access x values from each data point. |
yAccessor | string | function | — | "y" | Field name or function to access y values from each data point. |
valueAccessor | string | function | — | "value" | Field name or function to access cell values for color encoding. |
colorScheme | string | — | "blues" | Color scheme: "blues", "reds", "greens", "viridis", or "custom". |
customColorScale | d3 scale | — | — | Custom color scale (used when colorScheme is "custom"). |
showValues | boolean | — | false | Show values as text labels in cells. |
valueFormat | function | — | — | Format function for cell value labels. |
cellBorderColor | string | — | "#fff" | Border color of heatmap cells. |
cellBorderWidth | number | — | 1 | Border width of heatmap cells. |
enableHover | boolean | — | true | Enable hover annotations on cells. |
tooltip | object | function | — | — | Tooltip configuration or render function. |
width | number | — | 600 | Chart width in pixels. |
height | number | — | 400 | Chart height in pixels. |
margin | object | — | { top: 50, bottom: 60, left: 70, right: 80 } | Margin around the chart area. |
xLabel | string | — | — | Label for the x-axis. |
yLabel | string | — | — | Label for the y-axis. |
title | string | — | — | Chart title displayed at the top. |
frameProps | object | — | — | Additional StreamXYFrame props for advanced customization. Escape hatch to the full Frame API. |
showLegend | boolean | — | false | Show a gradient color legend for the value scale. |
legendPosition | "right" | "left" | "top" | "bottom" | — | "right" | Position of the gradient legend relative to the chart. |
Graduating to the Frame
When you need more control — custom bin functions, hexbins, contour plots — graduate to StreamXYFrame directly. Every Heatmap is just a configured StreamXYFrameunder the hood.
Chart (simple)
JSX
import { Heatmap } from "semiotic" <Heatmap data={activityData} xAccessor="day" yAccessor="hour" valueAccessor="value" colorScheme="viridis" showValues={true} xLabel="Day" yLabel="Hour" />
Frame (full control)
JSX
import { StreamXYFrame } from "semiotic" import { scaleSequential } from "d3-scale" import { interpolateViridis } from "d3-scale-chromatic" <StreamXYFrame summaries={{ coordinates: activityData }} xAccessor="day" yAccessor="hour" summaryType={{ type: "heatmap", xBins: 5, yBins: 5, binValue: items => { const sum = items.reduce((a, d) => a + d.value, 0) return sum / items.length } }} summaryStyle={d => ({ fill: colorScale(d.value), stroke: "#fff", strokeWidth: 1 })} axes={[ { orient: "left", label: "Hour" }, { orient: "bottom", label: "Day" } ]} hoverAnnotation={true} size={[600, 400]} />
The frameProps prop on Heatmap lets you pass any StreamXYFrame prop without fully graduating:
JSX
// Use frameProps as an escape hatch <Heatmap data={activityData} xAccessor="day" yAccessor="hour" valueAccessor="value" frameProps={{ annotations: [ { type: "highlight", day: 3, hour: 12, label: "Peak" } ] }} />
- Scatterplot — for individual point-level data without aggregation
- BubbleChart — encode a third variable via bubble size instead of cell color
- StreamXYFrame — the underlying Frame with full control over every rendering detail
- Annotations — adding callouts, highlights, and notes to any visualization
- Tooltips — custom tooltip content and positioning