Guide / Controls / Readouts

Stat tile

A big number, its change, and a faint trend

When to use it. One number, told whole: the value large with its unit, a change arrow and percent against a reference, a background tinted by the threshold band the value sits in, and a faint sparkline of recent values under it. The one-control replacement for a label + sparkline + status light stacked by hand. Read-only.

Type
statTile
Also titled
Stat Tile
Default size
3 rows × 2 columns
Symbol
number.square
Docs
Docs complete
Search for it as
  • kpi
  • metric
  • stat
  • number
  • counter
  • big number
Stat tile: Daily downloads against yesterday
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Titlelabeltext—

The caption above the number

Shows this text as the tile's title in the title text size.

hideLabelhideLabelon / offfalse (off)

Number without a caption

Removes the title line when on, leaving the number alone.

Unitunittext—

What the number is measured in

Shows the unit small beside the number in the viewer's local unit, e.g. celsius reads \u00b0F in the US.

Number sizevalueSizenumber14–80 ptstep 134

How big the number is

Sets the big number's size from 14 to 80 points.

Number formatformatValuetext—

How the number is written

Formats the big number, e.g. decimal:1 shows 72.5 and decimal:0 shows 73.

Decimal placesstepnumber—

How many digits after the point

Rounds the number when no format is set, e.g. 1 shows 72.5 and 0 shows 73.

History lengthsparklinePointsnumber5–500step 550

How far back the faint trend reaches

Keeps the last 5 to 500 readings in the trend line; more points show a longer history.

Line widthlineWidthnumber0.5–12 ptstep 0.52

How thick the trend line is

Sets the trend line stroke from 0.5 to 12 points.

Colortintcolor—

The trend line color

Paints the faint trend line in one color when there are no color zones.

GlowglowRadiusnumber0–30 ptstep 10

A soft halo around the trend line

Adds a glow behind the trend line from 0 (off) to 30 points wide.

Line endslineCapchoiceone of 3round

The shape of the trend line's ends

Rounds, flattens or squares the two ends of the trend line.

  • round defaultsoft rounded ends
  • buttflat ends cut exactly at the data point
  • squareflat ends that stick out half a stroke past the data point
hideBackgroundhideBackgroundon / offfalse (off)

The card behind the number

Removes the card fill and its zone tint when on so the number floats on the layout.

Motionanimationchoiceone of 5—

How the number moves when it changes

The number rolls to each new value; instant swaps it with no roll.

  • smoothan even roll and the default
  • snappya quick roll that settles fast
  • bouncyovershoots slightly then springs back
  • gentlea slow and soft roll
  • instantswaps straight to the new number with no roll
Compare againststatTileConfig.referencenumber—

The number to compare with

Sets the baseline in the tile's unit; the arrow and change show the value minus this.

Live reference pathstatTileConfig.referencePathtext—

Where a live comparison number comes from

Reads the baseline from this dot path in the same data as the value and replaces Compare against once it arrives.

Change shown asstatTileConfig.deltaModechoiceone of 2percent

How the change is written

Shows the change as a percent of the baseline or as the plain difference in the tile's unit.

  • percent defaultchange as a percent of the baseline
  • absolutechange as the plain difference in the value's unit
Up is badstatTileConfig.invertDeltaon / offfalse (off)

Swap good and bad colors

When on a rise is drawn red and a fall green instead of the reverse.

Color zonesstatTileConfig.thresholdslist—

Background colors for different ranges of values

Tints the card with the color of the zone the value sits in, e.g. green to 250 then amber to 600 then red.

Critical at or abovestatTileConfig.criticalAbovenumber—

The value where the tile turns solid

At or above this value the whole tile fills solid with its zone color and white text.

Critical at or belowstatTileConfig.criticalBelownumber—

The low value where the tile turns solid

At or below this value the whole tile fills solid with its zone color and white text.

Show trendstatTileConfig.showSparklineon / offtrue (on)

The faint trend under the number

Draws the recent-history line under the number when on and hides it when off.

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 show large, or a list of numbers that becomes the trend and shows its last point

the number updates and joins the faint trend under it; a list replaces the trend

Example: 40

Sample

The placeholder value the editor shows before real data arrives.

  • 40 then 75

Examples

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

Daily downloads against yesterday

Demonstrates reference with thresholds: the percent change against 1142 shows under the number and the card tints amber below 500 and green above.

JSON 17 lines
{
  "type": "statTile",
  "id": "downloads",
  "position": [0, 0],
  "span": [3, 2],
  "label": "Downloads",
  "unit": "today",
  "formatValue": "decimal:0",
  "statTileConfig": {
    "reference": 1142,
    "thresholds": [
      { "limit": 500, "color": "#FF9F0A" },
      { "limit": 100000, "color": "#34C759" }
    ]
  },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "stats" }, "valuePath": "downloads" }]
}

Open in CAR-TER

Stat tile: Daily downloads against yesterday
Rendered by the app

Latency where up is bad, with a live reference

Demonstrates referencePath, invertDelta and criticalAbove: the baseline arrives with the value, a rise reads red, and at 600 ms or more the whole tile fills solid red.

JSON 20 lines
{
  "type": "statTile",
  "id": "p95",
  "position": [0, 2],
  "span": [3, 2],
  "label": "p95 latency",
  "unit": "ms",
  "formatValue": "decimal:0",
  "statTileConfig": {
    "referencePath": "p95_prev",
    "invertDelta": true,
    "thresholds": [
      { "limit": 250, "color": "#34C759" },
      { "limit": 600, "color": "#FF9F0A" },
      { "limit": 100000, "color": "#FF453A" }
    ],
    "criticalAbove": 600
  },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "stats" }, "valuePath": "p95" }]
}

Open in CAR-TER

Stat tile: Latency where up is bad, with a live reference
Rendered by the app

Absolute change, no trend

Demonstrates deltaMode: "absolute" and showSparkline: false: the change reads as a plain difference of users and no history line is drawn.

JSON 9 lines
{
  "type": "statTile",
  "id": "sessions",
  "position": [3, 0],
  "span": [2, 2],
  "label": "Active sessions",
  "unit": "users",
  "statTileConfig": { "reference": 300, "deltaMode": "absolute", "showSparkline": false }
}

Open in CAR-TER

Stat tile: Absolute change, no trend
Rendered by the app

Critical when low

Demonstrates criticalBelow: at 15 or less the tile fills solid with its band colour, useful for a battery or a stock level.

JSON 3 lines
{ "type": "statTile", "id": "stock", "position": [3, 2], "span": [2, 2], "label": "Stock", "unit": "units",
  "statTileConfig": { "reference": 100, "criticalBelow": 15,
    "thresholds": [ { "limit": 15, "color": "#FF453A" }, { "limit": 40, "color": "#FF9F0A" }, { "limit": 100000, "color": "#34C759" } ] } }

Open in CAR-TER

Stat tile: Critical when low
Rendered by the app

Number alone

Demonstrates the minimal control: with no statTileConfig the tile is just a title and a number on a plain card.

JSON 1 line
{ "type": "statTile", "id": "plain", "position": [0, 0], "span": [2, 2], "label": "Visitors" }

Open in CAR-TER

Stat tile: Number alone
Rendered by the app

Number size, decimals and no title

Demonstrates valueSize: 56, step: 2 and hideLabel: true: a large number with two decimals and the title line removed.

JSON 17 lines
{
  "type": "statTile",
  "id": "big",
  "position": [
    0,
    0
  ],
  "span": [
    3,
    2
  ],
  "label": "Balance",
  "hideLabel": true,
  "valueSize": 56,
  "step": 2,
  "unit": "usd"
}

Open in CAR-TER

Stat tile: Number size, decimals and no title
Rendered by the app

Converted unit

Demonstrates unit: "celsius": the value arrives in °C but reads °F in the US, while thresholds and reference stay in °C.

JSON 2 lines
{ "type": "statTile", "id": "outside", "position": [0, 0], "span": [3, 2], "label": "Outside", "unit": "celsius", "formatValue": "decimal:1",
  "statTileConfig": { "reference": 18 } }

Open in CAR-TER

Stat tile: Converted unit
Rendered by the app

Trend line style

Demonstrates sparklinePoints: 120, lineWidth: 4, tint, glowRadius: 10 and lineCap: "butt": a longer, thicker, glowing trend with flat ends.

JSON 2 lines
{ "type": "statTile", "id": "trend", "position": [0, 0], "span": [3, 4], "label": "Power", "unit": "W", "sparklinePoints": 120, "lineWidth": 4, "tint": "#00D4FF", "glowRadius": 10, "lineCap": "butt",
  "statTileConfig": { "reference": 400 } }

Open in CAR-TER

Stat tile: Trend line style
Rendered by the app

Motion and bare card

Demonstrates animation: "bouncy" (the number overshoots as it rolls) and hideBackground: true (no card or zone tint, so the number floats).

JSON 15 lines
{
  "type": "statTile",
  "id": "floaty",
  "position": [
    0,
    0
  ],
  "span": [
    3,
    2
  ],
  "label": "Score",
  "animation": "bouncy",
  "hideBackground": true
}

Open in CAR-TER

Stat tile: Motion and bare card
Rendered by the app

Tile with long-press detail

Demonstrates longPressGroup: the tile itself is display-only, so holding it opens a popup with a longer history.

JSON 19 lines
{
  "type": "statTile",
  "id": "cpu-load",
  "position": [0, 0],
  "span": [3, 2],
  "label": "CPU load",
  "unit": "percent",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "device": "server" }, "valuePath": "cpu" }],
  "longPressGroup": {
    "position": [0, 0],
    "span": [2, 2],
    "id": "cpu-detail",
    "label": "CPU history",
    "grid": { "columns": 2, "rows": 2 },
    "children": [
      { "type": "sparkline", "id": "cpu-history", "position": [0, 0], "span": [2, 2], "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "device": "server" }, "valuePath": "cpu" }] }
    ]
  }
}

Open in CAR-TER

Stat tile: Tile with long-press detail
Rendered by the app

Themed tile

Demonstrates the theme fields: rounder corners, more inner spacing, custom fill, border and larger title text.

JSON 2 lines
{ "type": "statTile", "id": "theme-demo", "position": [0, 0], "span": [3, 2], "label": "Revenue",
  "theme": { "cornerRadius": 22, "controlPadding": 14, "surfacePrimary": "#1C1C2E", "accentColor": "#34C759", "foregroundColor": "#FFFFFF", "secondaryColor": "#FFFFFF99", "borderColor": "#34C75966", "borderWidth": 2, "labelFontSize": 16 } }

Open in CAR-TER

Stat tile: Themed tile
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 “Daily downloads against yesterday” on your phone.

    carterkit demo statTile --example 'Daily downloads against yesterday'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Data Flow

The tile listens like a gauge: its sync delivers a number. Each number also appends to the tile's rolling history (the same buffer a Title uses, capped at sparklinePoints); a numeric array replaces the history and the number shows its last point.

  • Delta = value − reference. Percent mode divides by |reference|; a missing reference — or a zero one in percent mode — hides the delta rather than showing ∞ or NaN. A change that rounds to 0.0% shows a flat arrow in the muted colour.
  • Colour: up is good (green) and down is bad (red) unless invertDelta flips them.
  • Thresholds: sorted by limit, the value takes the first band whose limit it does not exceed; below the first → the first band, above the last → the last. The tint is soft by default; criticalAbove/criticalBelow switch it to a solid fill.

Behavior

  • The number rolls with the native numeric-text transition (via the shared numeric readout); the band tint cross-fades.
  • Tapping does nothing — the tile is display-only. Add a longPressGroup for detail.
  • VoiceOver reads the title, the value with its unit, and "up 12.4%" / "down" / "unchanged".
  • Free control (no Pro unlock).
  • Unit — the same segment semantics on a dial
  • Title — the history on its own
  • Border thickness — a number without the chrome

Generated from ControlDocs/stat-tile.md. Something unclear or missing? Tell me.