Guide / Controls / Readouts

Status dot

A colored dot: OK, busy, or off

When to use it. A compact indicator that displays state as a colored dot or badge. The color changes based on synced state values mapped through statusColors.

Type
statusLight
Also titled
Status Light
Default size
1 row × 1 column
Symbol
circle.fill
Docs
Docs complete
Search for it as
  • led
  • indicator
  • status
  • health
  • up down
  • traffic light
Status dot: Plain dot with a fixed color
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Titlelabeltext—

The name shown next to the light

Shows this text beside the dot in the label font size (8-24 pt, default 12).

Colortintcolor#34C759

The light's color when no state color applies

Colors the dot or badge and its glow in this color until a state with its own color in statusColors is received.

Colors for each statusstatusColorsobject—

Which color each status shows

Recolors the light to the color matching the current state text; a state with no entry keeps the tint color.

Sizesizechoiceone of 3default

How big the light is drawn

Sets the dot diameter to 8, 12 or 18 points; the badge style scales with it.

  • smalla tiny 8 pt dot for dense rows
  • default defaulta standard 12 pt dot
  • largea bold 18 pt dot you can read across the room
Shapestylechoiceone of 2dot

Plain dot or a pill with words

Switches between a round dot beside the label and a capsule that spells out the current state in text.

  • dot defaulta round colored light with the label beside it
  • badgea rounded pill that shows the state name in its tint
Glowglownumber0–1step 0.050.3

A soft halo around the light

Sets the halo strength from 0 (flat) to 1 (full); in the badge shape it sets how strongly the pill is tinted.

Pulsepulseon / offfalse (off)

Whether the light breathes

Makes the light fade in and out continuously while true; false keeps it steady.

Starting statusdefaultValuetext—

The status shown before any update arrives

Picks which statusColors entry the light shows at first, until a synced value or a live update replaces it.

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, defaultstring

a state word such as online, degraded or offline

the light takes the color listed for that word in the status colors (or its own color when the word is not listed), and the badge shape spells the word out

Example: online

Sample

The placeholder value the editor shows before real data arrives.

  • online then offline

Examples

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

Plain dot with a fixed color

Shows the simplest light: a small green dot beside a name, with no live data, so it always shows the tint color.

JSON 7 lines
{
  "type": "statusLight",
  "id": "power-light",
  "position": [0, 0],
  "label": "Power",
  "tint": "#34C759"
}

Open in CAR-TER

Status dot: Plain dot with a fixed color
Rendered by the app

Starting status and state colors

Shows how defaultValue picks the first state: the light starts amber as "degraded" until a live value arrives.

JSON 8 lines
{
  "type": "statusLight",
  "id": "link-status",
  "position": [0, 1],
  "label": "Uplink",
  "statusColors": { "online": "#34C759", "degraded": "#FF9500", "offline": "#FF3B30" },
  "defaultValue": "degraded"
}

Open in CAR-TER

Status dot: Starting status and state colors
Rendered by the app

Badge look

Shows the pill shape: the light becomes a capsule that spells out the current state ("online") in the state color.

JSON 9 lines
{
  "type": "statusLight",
  "id": "db-badge",
  "position": [1, 0],
  "label": "Database",
  "style": "badge",
  "statusColors": { "online": "#34C759", "offline": "#FF3B30" },
  "defaultValue": "online"
}

Open in CAR-TER

Status dot: Badge look
Rendered by the app

Pulsing look

Shows the pulsing look: the dot breathes continuously to draw the eye to something that needs watching.

JSON 8 lines
{
  "type": "statusLight",
  "id": "alarm-light",
  "position": [1, 1],
  "label": "Alarm",
  "tint": "#FF3B30",
  "pulse": true
}

Open in CAR-TER

Status dot: Pulsing look
Rendered by the app

Small and large sizes

Shows the size scale: a large 18 pt dot with a strong glow reads from across the room; set "size": "small" for an 8 pt dot in dense rows.

JSON 9 lines
{
  "type": "statusLight",
  "id": "big-light",
  "position": [2, 0],
  "label": "Garage door",
  "size": "large",
  "glow": 0.8,
  "tint": "#FF9500"
}

Open in CAR-TER

Status dot: Small and large sizes
Rendered by the app

Server status indicator (live data)

Shows a live binding: the server broadcasts {"msg_type": "server_health", "state": "degraded"} and state picks the statusColors key, so the badge turns amber and pulses.

JSON 16 lines
{
  "type": "statusLight",
  "id": "server-status",
  "position": [2, 1],
  "label": "API Server",
  "statusColors": {
    "online": "#34C759",
    "degraded": "#FF9500",
    "offline": "#FF3B30"
  },
  "size": "large",
  "style": "badge",
  "pulse": true,
  "defaultValue": "offline",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "server_health" }, "valuePath": "state" }]
}

Open in CAR-TER

Status dot: Server status indicator (live data)
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 “Plain dot with a fixed color” on your phone.

    carterkit demo statusLight --example 'Plain dot with a fixed color'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Notes

The status light has no tap, long-press or detail action; it only displays state. Every hinted editor field (Title, Color, Size, Shape, Glow, Pulse) changes something visible on screen.

Generated from ControlDocs/status-light.md. Something unclear or missing? Tell me.