Guide / Controls / Charts

Heat grid

Colored squares that show how much

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
Heat grid: Continuous telemetry 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
FieldTypeDefaultWhat it does
haptichapticchoiceone 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
Titlelabeltext—

The caption above the grid

Shows this text as the header above the grid in the title text size.

heatmapConfigheatmapConfigobject—

The grid's settings bundle

Holds the cell look, labels, editing and calendar options below; leave it out for a plain read-only grid.

Colortintcolor#667eea

The main color of the grid

Colors the top of the default ramp or the palette accent when no scale colors are set.

formatValueformatValuetext—

How numbers are written

Formats the scale legend and in-cell numbers, e.g. suffix:°C turns 24 into 24°C.

calendarheatmapConfig.calendaron / offfalse (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.weekStartsOnchoiceone 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.weeksnumber1–106step 1—

How many weeks the calendar shows

Keeps only the most recent N weeks (1 to 106) and drops older ones.

cellActionheatmapConfig.cellActionobject—

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.cellCornerRadiusnumber0–30 ptstep 13

How rounded each square is

Rounds each square cell from sharp (0) to 30 points; circle cells ignore it.

cellCornerheatmapConfig.cellCornernumber0–30step 13

Older name for cell roundness

Rounds square cells from 0 to 30 points; cellCornerRadius wins when both are set.

Cell spacingheatmapConfig.cellGapnumber0–40 ptstep 12

The space between cells

Sets the gap between neighbouring cells from 0 to 40 points.

Cell shapeheatmapConfig.cellShapechoiceone of 2square

Squares or dots

Draws each cell as a rounded square or as a circle for a dot-matrix look.

  • square defaultrounded squares that tile the grid
  • circleround dots like an LED matrix
Scale colorsheatmapConfig.colorsstring[]—

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.discreteon / offfalse (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.dragon / offtrue (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.editableon / offfalse (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.sendModetext—

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.showColLabelson / offtrue (on)

Labels along the top

Shows the column names above the grid and thins them out when space is tight.

Row labelsheatmapConfig.showRowLabelson / offtrue (on)

Labels down the side

Shows the row names at the left edge of the grid.

Scale legendheatmapConfig.showScaleon / offfalse (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.showValueson / offfalse (off)

Numbers inside the cells

Prints each cell's number on it when the cells are big enough to read.

vMaxheatmapConfig.vMaxnumber—

The value at the hottest color

Sets the number that maps to the last scale color; larger values stay at that color.

vMinheatmapConfig.vMinnumber—

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
FieldTypeDefaultWhat it does
Label colortheme.secondaryColorcolor#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
SendsWhenTypeWhat it sends
When you edit a cellcellchangejson

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
TakesFromTypeWhat it does
cellsshowhub, mqtt, http, storejson

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

Example: {"values": [[1, 2], [3, 4]], "rows": ["Row 1", "Row 2"], "cols": ["Column 1", "Column 2"]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"values": [[1, 2, 3], [3, 2, 1], [2, 3, 1]], "rows": ["Row 1", "Row 2", "Row 3"], "cols": ["Column 1", "Column 2", "Column 3"]} then {"values": [[3, 2, 1], [1, 2, 3], [2, 1, 3]], "rows": ["Row 1", "Row 2", "Row 3"], "cols": ["Column 1", "Column 2", "Column 3"]}

Examples

6 examples, each one a control you can paste into a layout.

Continuous telemetry heatmap

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.

JSON 11 lines
{
  "type": "heatmap",
  "id": "rack-temps",
  "defaultValue": "{\"rows\":[\"Mon\",\"Tue\",\"Wed\"],\"cols\":[\"00\",\"06\",\"12\",\"18\"],\"values\":[[24,31,62,45],[28,55,81,49],[22,38,74,68]]}",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Rack temperatures",
  "formatValue": "suffix:°C",
  "heatmapConfig": { "colors": ["#1B2845", "#667eea", "#FF9500", "#FF6B6B"], "showScale": true, "vMin": 20, "vMax": 90 },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "rack_temps" }, "valuePath": "grid" }]
}

Open in CAR-TER

Heat grid: Continuous telemetry heatmap
Rendered by the app

Weekly schedule programmer (editable, discrete)

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.

JSON 15 lines
{
  "type": "heatmap",
  "id": "thermostat-schedule",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Heating schedule",
  "heatmapConfig": {
    "discrete": true,
    "colors": ["#FFFFFF14", "#667eea", "#FF9500"],
    "editable": true,
    "sendMode": "matrix",
    "cellAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "schedule_set", "schedule": "{{value}}" } }
  },
  "defaultValue": "{\"rows\":[\"Mon\",\"Tue\",\"Wed\",\"Thu\",\"Fri\",\"Sat\",\"Sun\"],\"cols\":[\"6\",\"9\",\"12\",\"15\",\"18\",\"21\"],\"values\":[[0,1,0,0,1,1],[0,1,0,0,1,1],[0,1,0,0,1,1],[0,1,0,0,1,1],[0,1,0,0,1,2],[1,1,1,1,1,2],[1,1,1,1,1,0]]}"
}

Open in CAR-TER

Heat grid: Weekly schedule programmer (editable, discrete)
Rendered by the app

LED matrix pixel editor

Demonstrates cellShape: circle with cellAction firing per cell: each tap cycles a dot through five colors and sends that one pixel.

JSON 16 lines
{
  "type": "heatmap",
  "id": "led-editor",
  "position": [0, 0],
  "span": [4, 4],
  "label": "LED panel",
  "heatmapConfig": {
    "discrete": true,
    "colors": ["#1A1A1A", "#FF3B30", "#34C759", "#007AFF", "#FFCC00"],
    "cellShape": "circle",
    "cellGap": 3,
    "editable": true,
    "cellAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "led_set", "pixel": "{{value}}" } }
  },
  "defaultValue": "[[0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0]]"
}

Open in CAR-TER

Heat grid: LED matrix pixel editor
Rendered by the app

Activity calendar (day-keyed)

Demonstrates calendar mode with weekStartsOn and showScale: day-keyed counts become a week-by-week grid where tapping a day reads its date and value.

JSON 9 lines
{
  "type": "heatmap",
  "id": "reading-calendar",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Reading days",
  "heatmapConfig": { "calendar": true, "weekStartsOn": "monday", "showScale": true },
  "defaultValue": "{\"2026-01-03\":1,\"2026-01-04\":1,\"2026-01-05\":2,\"2026-01-06\":2,\"2026-02-27\":1,\"2026-02-28\":1,\"2026-03-01\":1,\"2026-03-02\":1,\"2026-03-13\":1,\"2026-03-14\":1,\"2026-03-15\":1}"
}

Open in CAR-TER

Heat grid: Activity calendar (day-keyed)
Rendered by the app

Recent weeks with values in cells

Demonstrates weeks, showValues and formatValue: the calendar keeps only the latest 8 weeks and cell numbers are written with a unit.

JSON 10 lines
{
  "type": "heatmap",
  "id": "recent-steps",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Recent activity",
  "formatValue": "suffix: km",
  "heatmapConfig": { "calendar": true, "weeks": 8, "showValues": true, "cellCornerRadius": 6, "cellGap": 3 },
  "defaultValue": "{\"2026-10-12\":3,\"2026-10-13\":5,\"2026-10-20\":2,\"2026-11-01\":8,\"2026-11-02\":4}"
}

Open in CAR-TER

Heat grid: Recent weeks with values in cells
Rendered by the app

Tap-only tick board (drag off, per-cell sends)

Demonstrates drag: false and sendMode: cell: each tap toggles one square between 0 and the top value and sends just that cell.

JSON 19 lines
{
  "type": "heatmap",
  "id": "habit-board",
  "position": [0, 0],
  "span": [3, 3],
  "label": "Habits",
  "heatmapConfig": {
    "editable": true,
    "drag": false,
    "sendMode": "cell",
    "vMin": 0,
    "vMax": 1,
    "colors": ["#1B2845", "#34C759"],
    "showRowLabels": true,
    "showColLabels": true,
    "cellAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "habit_set", "cell": "{{value}}" } }
  },
  "defaultValue": "{\"rows\":[\"Read\",\"Walk\",\"Stretch\"],\"cols\":[\"Mon\",\"Tue\",\"Wed\",\"Thu\"],\"values\":[[1,0,1,1],[0,0,1,0],[1,1,0,0]]}"
}

Open in CAR-TER

Heat grid: Tap-only tick board (drag off, per-cell sends)
Rendered by the app

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Continuous telemetry heatmap” on your phone.

    carterkit demo heatmap --example 'Continuous telemetry heatmap'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

discrete mode each value is an index into a palette. Flip on editable and the

Wide: [2, 4] for a dashboard strip; taller for schedule grids (one row per day).

HeatmapConfig

Color Mapping

Field Type Default Description
colors string[] tint ramp Continuous: 2+ gradient stops. Discrete: the palette (value = index)
discrete bool false Treat values as palette indices instead of a continuous range
vMin / vMax number data range Continuous color-scale bounds

Cells

Field Type Default Description
cellCornerRadius number 3 Cell corner rounding in points, 0–30 (square cells only)
cellCorner number 3 Older name of cellCornerRadius; the newer key wins
cellGap number 2 Gap between cells
cellShape string "square" square or circle (circle reads as dot-matrix/LED)

Labels & Legend

Field Type Default Description
showRowLabels bool true Row labels down the leading edge (when rows present)
showColLabels bool true Column labels along the top (when cols present; auto-thinned)
showScale bool false Gradient scale legend under the grid (continuous only)
showValues bool false Numeric value inside each cell (when cells are large enough)

Editing

Field Type Default Description
editable bool false Tap cycles a cell (discrete: next palette index; continuous: 0 ↔ vMax toggle)
drag bool true Drag paints the first-touched cell's new value across cells
cellAction ActionDefinition — 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):

{
  "type": "heatmap", "id": "reading-days", "label": "Reading days",
  "heatmapConfig": { "calendar": true },
  "sync": [{ "method": "local", "collection": "books",
             "groupBy": { "range": ["started", "finished"], "bucket": "day" } }]
}

Sync Payload Structure

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:

{
  "rows": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
  "cols": ["00", "03", "06", "09", "12", "15", "18", "21"],
  "values": [
    [0, 0, 1, 3, 3, 2, 1, 0],
    [0, 0, 1, 3, 3, 2, 1, 0],
    [0, 0, 2, 3, 3, 3, 2, 1],
    [0, 0, 1, 3, 3, 2, 1, 0],
    [0, 0, 1, 2, 3, 3, 3, 2],
    [1, 0, 0, 1, 2, 3, 3, 2],
    [1, 0, 0, 1, 2, 2, 1, 0]
  ]
}

Behavior

  • Dataset pushes animate cell colors; edits render instantly (a local draft holds until the next push)
  • Tap cycles: discrete (value + 1) % palette.count, continuous 0 ↔ vMax
  • 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

Generated from ControlDocs/heatmap.md. Something unclear or missing? Tell me.