Fields 10 fields you can set on a sparkline control. Every control also takes the shared fields (id, position, span, sync, action).
Fields Field Type Default What it does Time window sparklinePointsnumber 5–500 step 5 50How many readings the line keeps
Keeps only the newest this-many readings on the line; older ones drop off the left.
Line width lineWidthnumber 0.5–12 pt step 0.5 — How thick the line is
Draws the line this many points thick; when not set it grows with the control's height.
sparklineFill sparklineFillon / off false (off) Shade under the line
Fills the area under the line with a fading tint when on; off leaves just the line.
Glow glowRadiusnumber 0–30 pt step 1 0A soft halo around the line
Adds a soft glow in the line's own color behind it; 0 turns it off.
Line ends lineCapchoice one of 3 roundShape of the line's ends
Shapes the two ends of the line as rounded, flat or squared off.
round default rounded ends and the default butt flat ends that stop exactly at the last point square flat ends that extend a little past the last point colorByValue colorByValuelist — Colour the line by how high it is
Colors the line and fill by height: each part takes the color of the zone its value falls in.
colorBlend colorBlendnumber 0–1 step 0.05 0Hard or soft color edges
Softens the edges between the color zones, from sharp bands at 0 to one smooth gradient at 1.
tint tintcolor #667eeaColor of the line
Colors the line and its fill; color zones replace it when set.
Title labeltext — The title and latest number
Shows this text at the top left, with the newest reading at the top right.
defaultValue defaultValuelist — Starting readings shown until new ones arrive
Draws these numbers as the line until real readings arrive.
Emits and receives What this control sends when you use it, and what it can show or follow when data arrives.
Receives Receives Takes From Type What it does value showhub, mqtt, http, sensor, store, derive, default number a number to add to the line as its newest point, or a list of numbers that becomes the whole line
a single number joins the right end and the oldest point drops off once the line is full; a list replaces the line, skipping empty entries
Example: 40
Sample The placeholder value the editor shows before real data arrives.
[41, 40, 44, 43, 47, 45] then 48Examples 4 examples, each one a control you can paste into a layout.
A filled trend of the last 100 room temperatures, arriving live from another device.
JSON 11 lines Copy {
"type": "sparkline",
"id": "temp-history",
"position": [0, 0],
"span": [1, 3],
"sparklinePoints": 100,
"sparklineFill": true,
"tint": "#FF6B6B",
"label": "Temperature",
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "room": "living" }, "valuePath": "temperature" }]
}Open in CAR-TER ↗
Rendered by the app Light Dark A bare green line of the last 30 CPU readings with no title.
JSON 9 lines Copy {
"type": "sparkline",
"id": "cpu-load",
"position": [0, 2],
"sparklinePoints": 30,
"tint": "#34C759",
"hideLabel": true,
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "device": "server" }, "valuePath": "cpu_load" }]
}Open in CAR-TER ↗
Rendered by the app Light Dark A 48-hour forecast curve that is replaced whole on every poll.
JSON 11 lines Copy {
"type": "sparkline",
"id": "temp-forecast",
"position": [1, 0],
"span": [1, 4],
"sparklinePoints": 48,
"sparklineFill": true,
"tint": "#0A84FF",
"label": "Next 48h",
"sync": [{ "method": "http", "url": "https://api.open-meteo.com/v1/forecast?latitude=42.36&longitude=-71.06&hourly=temperature_2m", "interval": 900, "valuePath": "hourly.temperature_2m" }]
}Open in CAR-TER ↗
The endpoint returns a plain numeric array at that path; each poll replaces the
whole series rather than appending a point.
Rendered by the app Light Dark Color the line green, amber or red by how high it is, softly blended, with a glowing edge and a seed series so it shows before data arrives.
JSON 15 lines Copy {
"type": "sparkline",
"id": "load-zones",
"position": [0, 0],
"span": [2, 2],
"label": "Load",
"sparklinePoints": 60,
"sparklineFill": true,
"lineWidth": 3,
"glowRadius": 8,
"lineCap": "round",
"colorByValue": [{ "limit": 50, "color": "#34C759" }, { "limit": 80, "color": "#FF9F0A" }, { "limit": 100, "color": "#FF3B30" }],
"colorBlend": 0.5,
"defaultValue": [20, 35, 30, 55, 70, 62, 85]
}Open in CAR-TER ↗
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.
Install the Python kit.
Copy pip install carterkit Show “Temperature history” on your phone.
Copy carterkit demo sparkline --example 'Temperature history' Swap in any example name from this page, or leave --example off for the first one.
carterkit quickstart · Get CAR-TER
Data Flow
Unlike other controls that store a single value, sparklines maintain a ring buffer of numeric values in AppState.sparklineBuffers. When the buffer exceeds sparklinePoints, the oldest value is dropped.
A sync payload feeds that buffer one of two ways, decided by what the valuePath resolves to:
Payload at valuePath
Effect
a number
Appended as one new point — the live-telemetry case
an array of numbers
Taken as the whole series, replacing the buffer (trimmed to the last sparklinePoints)
The array form is what a forecast or history endpoint returns, and is the same
shape Axis bottom accepts — so hourly.temperature_2m works in both. nulls inside
the array are skipped (feeds pad trailing hours with them). When an array arrives,
the sparkline's header value shows its last element.
The sparkline renders all points in the buffer as a line path, auto-scaling Y to the min/max of the current buffer.
Behavior
A numeric payload appends a point; a numeric array replaces the series
New data points animate in smoothly
The Y axis auto-scales to the min/max of current buffer data
When fewer than 2 points exist, shows a "--" placeholder
The latest value is shown in the header (right side) with animated numeric transition
On-control editing (C6)
The chart publishes its y range as a value axis and part label; colorByValue level dots in edit mode ride the line's right edge, bottom = lowest sample, top = highest, and snap to other levels. See SharedEditorContract.swift.
Shadow opacity — Base fields
Sync — How values are received
Unit — Often paired with sparklines in long-press detail views
Axis bottom — Multi-series bars/lines/areas/scatter when one trend isn't enough
Generated from ControlDocs/sparkline.md. Something unclear or missing? Tell me .