When to use it. A color-mapped matrix. In continuous mode values interpolate across a gradient ramp — server-room temperatures, signal strength, an activity calendar. In same grid becomes an input surface: tap cycles a cell, drag paints — a weekly schedule programmer, an LED-matrix pixel editor, or a step sequencer, straight from one flag.
Type
heatmap
Also titled
Heatmap
Default size
3 rows × 4 columns
Symbol
square.grid.3x3.fill
Docs
Docs complete
Search for it as
heat map
density
grid
intensity
matrix
calendar heatmap
Rendered by the app
Fields
24 fields you can set on a heatmap control. Every control also takes the shared fields (id, position, span, sync, action).
Fields
Field
Type
Default
What it does
haptichaptic
choiceone of 10
—
The buzz you feel on touch
A tap on the phone gives a short vibration of the chosen strength; none is silent.
noneno vibration
lighta faint tap
mediuma medium tap
heavya strong thud
softa muffled cushioned tap
rigida sharp crisp tap
selectiona tiny tick like a picker moving
successa happy double pulse
warninga cautionary pulse
errora harsh triple buzz
Titlelabel
text
—
The caption above the grid
Shows this text as the header above the grid in the title text size.
heatmapConfigheatmapConfig
object
—
The grid's settings bundle
Holds the cell look, labels, editing and calendar options below; leave it out for a plain read-only grid.
Colortint
color
#667eea
The main color of the grid
Colors the top of the default ramp or the palette accent when no scale colors are set.
formatValueformatValue
text
—
How numbers are written
Formats the scale legend and in-cell numbers, e.g. suffix:°C turns 24 into 24°C.
calendarheatmapConfig.calendar
on / off
false(off)
A day-by-day activity calendar
Lays day-keyed data out as 7 weekday rows by week columns with month labels; tapping a day shows its date and value.
weekStartsOnheatmapConfig.weekStartsOn
choiceone of 2
—
Which day starts each week
Sets the top row of each calendar column to Monday or Sunday.
mondayweeks run Monday to Sunday
sundayweeks run Sunday to Saturday
weeksheatmapConfig.weeks
number1–106step 1
—
How many weeks the calendar shows
Keeps only the most recent N weeks (1 to 106) and drops older ones.
cellActionheatmapConfig.cellAction
object
—
What happens when you edit a cell
Fires this action for every edit with {{value}} holding the row, column and new value as JSON.
Cell roundnessheatmapConfig.cellCornerRadius
number0–30 ptstep 1
3
How rounded each square is
Rounds each square cell from sharp (0) to 30 points; circle cells ignore it.
cellCornerheatmapConfig.cellCorner
number0–30step 1
3
Older name for cell roundness
Rounds square cells from 0 to 30 points; cellCornerRadius wins when both are set.
Cell spacingheatmapConfig.cellGap
number0–40 ptstep 1
2
The space between cells
Sets the gap between neighbouring cells from 0 to 40 points.
Cell shapeheatmapConfig.cellShape
choiceone of 2
square
Squares or dots
Draws each cell as a rounded square or as a circle for a dot-matrix look.
squaredefaultrounded squares that tile the grid
circleround dots like an LED matrix
Scale colorsheatmapConfig.colors
string[]
—
The colors the cells use
Continuous mode blends across these gradient stops (2 or more); stepped mode picks the color at each value's index.
Stepped scaleheatmapConfig.discrete
on / off
false(off)
Fixed steps instead of a blend
When on each value is a whole-number index into the colors list so cells show flat palette colors instead of a gradient.
dragheatmapConfig.drag
on / off
true(on)
Painting by dragging
When on a drag copies the first-touched cell's new value across every cell the finger crosses; off limits edits to single taps.
editableheatmapConfig.editable
on / off
false(off)
Lets you change the cells
When on tapping a cell cycles it to the next palette color or toggles between 0 and the top value.
sendModeheatmapConfig.sendMode
text
—
How often edits are sent
cell sends every change on its own while matrix waits about 0.4 seconds then sends the whole grid once.
Column labelsheatmapConfig.showColLabels
on / off
true(on)
Labels along the top
Shows the column names above the grid and thins them out when space is tight.
Row labelsheatmapConfig.showRowLabels
on / off
true(on)
Labels down the side
Shows the row names at the left edge of the grid.
Scale legendheatmapConfig.showScale
on / off
false(off)
A key under the grid
Adds a gradient legend beneath a continuous grid or a Less to More row in calendar mode.
Value labelsheatmapConfig.showValues
on / off
false(off)
Numbers inside the cells
Prints each cell's number on it when the cells are big enough to read.
vMaxheatmapConfig.vMax
number
—
The value at the hottest color
Sets the number that maps to the last scale color; larger values stay at that color.
vMinheatmapConfig.vMin
number
—
The value at the coolest color
Sets the number that maps to the first scale color; smaller values stay at that color.
Theme fields
Restyle one control by setting these in its theme object; a layout's theme sets them for every control.
Theme fields
Field
Type
Default
What it does
Label colortheme.secondaryColor
color
#FFFFFF99
How big the title text is
Colors the dimmest text and empty-cell ink in this color.
Emits and receives
What this control sends when you use it, and what it can show or follow when data arrives.
Emits
Emits
Sends
When
Type
What it sends
When you edit a cellcell
change
json
the edited cell as row, column and new value
Only when editable is on; each tapped or painted cell sends once. With sendMode matrix nothing is sent per cell; the whole grid goes out once, about 0.4 seconds after the edits stop
Example: {"row": 0, "col": 1, "value": 1}
Receives
Receives
Takes
From
Type
What it does
cellsshow
hub, mqtt, http, store
json
a grid of numbers, with optional row and column labels (a bare list of lists works too)
each cell recolors to its new number; your own edits show at once until the next push replaces them
Demonstrates a read-only continuous ramp with showScale, vMin/vMax and formatValue: hot cells glow orange to red and a legend runs under the grid, fed live over MeshSocket.
Demonstrates editable with discrete and sendMode: matrix: tapping or dragging recolors hours as off, comfort or boost, and the whole week is sent once edits pause.
Fired per edit; {{value}} = {"row", "col", "value"} JSON
sendMode
string
"cell"
cell fires per change; matrix fires the whole dataset once an edit burst settles (~0.4s)
If cellAction is omitted, edits fall back to the control's own action.
Calendar
Field
Type
Default
Description
calendar
bool
false
Activity calendar (GitHub style): a day-keyed payload laid out as 7 weekday rows × week columns
weekStartsOn
string
source's, else "monday"
"monday" or "sunday": the top row of each column
weeks
number
whole span (max 106)
Show only the most recent N weeks
Calendar mode reads a day-keyed payload instead of a matrix, so a local store
feeds it directly with groupBy {…, bucket: "day"} (the groups shape
{categories, series, rows:[{key, value}]}). A bare {"2026-01-03": 2, …} object
or [{"date": "2026-01-03", "value": 2}, …] also works; date-time keys use their
first 10 characters, non-date keys (the null bucket) are skipped, duplicates add up.
Days run from the first key to the last, zero-filled; slots before the first
day and after the last day in their week stay blank.
Cells are square. When the span does not fit the width (8pt minimum cells), the
oldest weeks drop off; the most recent day is always shown.
Month labels sit over the week holding the 1st; weekday labels on rows 2, 4, 6.
Color: a day at or below vMin (default 0) gets the empty color (colors[0], else a
faint neutral); others ramp across colors[1…] (default the tint) up to vMax
(default the busiest day). showScale adds a "Less … More" swatch row.
Tap a day to show its date and value beside the label; tap again to clear.
Calendar mode is read-only (editable is ignored). VoiceOver reads a summary
("41 active days from … to …, most on …").
Reading days from a book log (every day between started and finished):
A dense matrix plus optional axis labels — natural JSON or an encoded string.
{"values": <span class="wikibroken" title="unresolved: …">…</span>} with labels, or a bare <span class="wikibroken" title="unresolved: …">…</span> array of rows:
Dragging paints the brush value chosen by the first cell touched — fill a row in one stroke
Every cell change ticks a selection haptic and updates the control's stored dataset, so state readback returns the edited grid
sendMode: "matrix" batches an edit burst into a single dataset-sized action — ideal for schedule saves
Notes
calendar, weekStartsOn and weeks change nothing in a plain matrix grid; editable, drag and sendMode change nothing in calendar mode (read-only); showScale and cellShape apply as described above.
Ragged rows render (short rows read as 0) and are padded rectangular on first edit
A GitHub-style activity calendar is calendar: true fed by day keys (see Calendar); the app builds the 7-row × week grid
A step sequencer is an editable discrete grid where the server plays column-by-column