Guide / Controls / Charts

Trend line

A little line that shows how a number changes

When to use it. A tiny inline line chart that accumulates synced values over time. Read-only.

Type
sparkline
Also titled
Sparkline
Default size
2 rows × 2 columns
Symbol
chart.xyaxis.line
Docs
Docs complete
Search for it as
  • trend
  • mini chart
  • tiny chart
  • spark
  • history
  • line
Trend line: Temperature history
Rendered by the app

Fields

10 fields you can set on a sparkline control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
Time windowsparklinePointsnumber5–500step 550

How many readings the line keeps

Keeps only the newest this-many readings on the line; older ones drop off the left.

Line widthlineWidthnumber0.5–12 ptstep 0.5—

How thick the line is

Draws the line this many points thick; when not set it grows with the control's height.

sparklineFillsparklineFillon / offfalse (off)

Shade under the line

Fills the area under the line with a fading tint when on; off leaves just the line.

GlowglowRadiusnumber0–30 ptstep 10

A soft halo around the line

Adds a soft glow in the line's own color behind it; 0 turns it off.

Line endslineCapchoiceone of 3round

Shape of the line's ends

Shapes the two ends of the line as rounded, flat or squared off.

  • round defaultrounded ends and the default
  • buttflat ends that stop exactly at the last point
  • squareflat ends that extend a little past the last point
colorByValuecolorByValuelist—

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.

colorBlendcolorBlendnumber0–1step 0.050

Hard or soft color edges

Softens the edges between the color zones, from sharp bands at 0 to one smooth gradient at 1.

tinttintcolor#667eea

Color of the line

Colors the line and its fill; color zones replace it when set.

Titlelabeltext—

The title and latest number

Shows this text at the top left, with the newest reading at the top right.

defaultValuedefaultValuelist—

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
TakesFromTypeWhat it does
valueshowhub, mqtt, http, sensor, store, derive, defaultnumber

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 48

Examples

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

Temperature history

A filled trend of the last 100 room temperatures, arriving live from another device.

JSON 11 lines
{
  "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

Trend line: Temperature history
Rendered by the app

Compact sparkline (no label, no fill)

A bare green line of the last 30 CPU readings with no title.

JSON 9 lines
{
  "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

Trend line: Compact sparkline (no label, no fill)
Rendered by the app

Forecast series from an HTTP feed

A 48-hour forecast curve that is replaced whole on every poll.

JSON 11 lines
{
  "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.

Trend line: Forecast series from an HTTP feed
Rendered by the app

Colored zones with a glow

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
{
  "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.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Temperature history” on your phone.

    carterkit demo sparkline --example 'Temperature history'
  3. 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.