Charts — Realtime Heatmap — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/charts/realtime-heatmap

RealtimeHeatmap

charts

import { RealtimeHeatmap } from "semiotic"

Wraps: StreamXYFrame

RealtimeHeatmap renders a streaming 2D heatmap by binning continuous x/y data into a grid and color-encoding aggregated values. It wrapsStreamXYFrame withchartType="heatmap" and runtimeMode="streaming". Create a ref and call ref.current.push(point) to stream data in. Supports count, sum, and mean aggregation modes, plus realtime encoding features like decay and pulse.

Quick Start

Push data points with x and y coordinates. The heatmap bins them into a grid and colors each cell by the aggregated count. The sliding window keeps only the most recent points.

JSX

import { RealtimeHeatmap } from "semiotic" import { useRef, useEffect } from "react" function StreamingHeatmap() { const chartRef = useRef() const indexRef = useRef(0) useEffect(() => { const id = setInterval(() => { const i = indexRef.current++ chartRef.current?.push({ time: i, x: 50 + Math.sin(i * 0.03) * 30 + (Math.random() - 0.5) * 40, y: 50 + Math.cos(i * 0.05) * 25 + (Math.random() - 0.5) * 40, value: 1, }) }, 20) return () => clearInterval(id) }, []) return ( <RealtimeHeatmap ref={chartRef} timeAccessor="x" valueAccessor="y" heatmapXBins={20} heatmapYBins={15} aggregation="count" windowSize={500} showAxes={true} /> ) }

Examples

Sum Aggregation

Use aggregation="sum" to sum a numeric field per cell instead of counting. Useful for intensity or energy maps where each event carries a weight.

JSX

const zone = i % 3 const baseX = zone === 0 ? 20 : zone === 1 ? 50 : 80 const baseY = zone === 0 ? 70 : zone === 1 ? 40 : 60 chartRef.current?.push({ time: i, x: baseX + (Math.random() - 0.5) * 30, y: baseY + (Math.random() - 0.5) * 30, intensity: 5 + Math.random() * 15, }) <RealtimeHeatmap ref={chartRef} timeAccessor="x" valueAccessor="y" heatmapXBins={15} heatmapYBins={12} aggregation="sum" windowSize={400} showAxes={true} />

Decay + Pulse

Combine decay to fade older data and pulse to flash newly arrived cells. This makes it easy to see where activity is happening right now versus where it was moments ago.

JSX

<RealtimeHeatmap ref={chartRef} timeAccessor="x" valueAccessor="y" heatmapXBins={25} heatmapYBins={18} aggregation="count" windowSize={300} showAxes={true} decay={{ type: "exponential", halfLife: 150, minOpacity: 0.15 }} pulse={{ duration: 400, color: "rgba(255,255,255,0.5)" }} />

Props

Prop	Type	Required	Default	Description
`data`	array	—	`[]`	Controlled data array. Each object should contain fields matched by timeAccessor and valueAccessor.
`timeAccessor`	string \| function	—	`"time"`	Field name or function to access the x-axis value from each data point.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access the y-axis value from each data point.
`size`	[number, number]	—	`[500, 300]`	Chart dimensions as [width, height].
`margin`	object	—	—	Chart margins: { top, right, bottom, left }.
`arrowOfTime`	"left" \| "right"	—	`"right"`	Direction that time flows across the chart.
`windowMode`	"sliding" \| "growing"	—	`"sliding"`	Data retention strategy. "sliding" discards old points beyond windowSize.
`windowSize`	number	—	`200`	Ring buffer capacity when using sliding window mode.
`timeExtent`	[number, number]	—	—	Fixed x-axis domain. Defaults to auto-fit.
`valueExtent`	[number, number]	—	—	Fixed y-axis domain. Defaults to auto-fit.
`extentPadding`	number	—	—	Padding factor applied to auto-computed extents.
`heatmapXBins`	number	—	`20`	Number of bins along the x-axis.
`heatmapYBins`	number	—	`20`	Number of bins along the y-axis.
`aggregation`	"count" \| "sum" \| "mean"	—	`"count"`	How values are aggregated within each grid cell.
`showAxes`	boolean	—	`true`	Show canvas-drawn axes.
`background`	string	—	—	Background fill color for the chart area.
`enableHover`	boolean \| object	—	—	Enable hover annotations on cells.
`tooltipContent`	function	—	—	Custom tooltip render function. Receives hover data.
`onHover`	function	—	—	Callback fired on hover. Receives hover data or null.
`decay`	DecayConfig	—	—	Configurable opacity decay. { type: "linear"\|"exponential"\|"step", halfLife?, minOpacity?, stepThreshold? }
`pulse`	PulseConfig	—	—	Flash effect on new data. { duration?, color?, glowRadius? }
`staleness`	StalenessConfig	—	—	Data liveness indicator. { threshold?, dimOpacity?, showBadge?, badgePosition? }
`annotations`	array	—	—	Array of annotation objects.
`svgAnnotationRules`	function	—	—	Custom SVG annotation render function.
`tickFormatTime`	function	—	—	Custom formatter for x-axis tick labels.
`tickFormatValue`	function	—	—	Custom formatter for y-axis tick labels.
`className`	string	—	—	CSS class name for the chart container.

Graduating to the Frame

When you need full control — custom color scales, annotations, or combined chart types — graduate toStreamXYFrame directly. Every RealtimeHeatmap is just a configuredStreamXYFrame under the hood.

Chart (simple)

JSX

import { RealtimeHeatmap } from "semiotic" <RealtimeHeatmap ref={chartRef} timeAccessor="x" valueAccessor="y" heatmapXBins={20} heatmapYBins={15} aggregation="count" windowSize={500} enableHover />

Frame (full control)

JSX

import { StreamXYFrame } from "semiotic" <StreamXYFrame ref={frameRef} chartType="heatmap" runtimeMode="streaming" timeAccessor="x" valueAccessor="y" heatmapXBins={20} heatmapYBins={15} heatmapAggregation="count" windowSize={500} hoverAnnotation={true} showAxes={true} size={[500, 300]} />

Heatmap — static heatmap for pre-computed matrix data
RealtimeLineChart — streaming continuous line for time-series data
RealtimeSwarmChart — streaming scatter/swarm for individual data points
RealtimeHistogram — streaming temporal histograms with binned bars
RealtimeWaterfallChart — cumulative deltas as connected rising and falling bars
StreamXYFrame — the underlying Frame with full control over every rendering detail