Guide / Controls / Readouts

Text

A line of text, or a value with a caption

When to use it. A read-only text display. Shows static text or synced dynamic text. Stores a .string value when synced.

Type
label
Also titled
Label
Default size
1 row × 2 columns
Symbol
textformat
Docs
Docs complete
Search for it as
  • text
  • title
  • heading
  • caption
  • readout
  • words
Text: Time since (plant watering)
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Texttexttext—

Text to show until a connected value is available

Sets the words on the label; a synced value replaces them as soon as one arrives.

Other textlabeltext—

A second place to put the words

Shows this text when Text is empty; the label reads the same either way.

Second linesubtitletext—

A smaller gray line under the words

Adds a compact second line in the caption size and the theme's secondary color; leave it empty for a single line.

Lineslinesnumber0–10step 11

How many lines the words may use

Keeps the text on one line, or lets it wrap onto up to 10 lines; 0 wraps as far as it needs.

Symbolicontext—

A small picture shown before the words

Draws the named SF Symbol in front of the text, in the same color and size.

Lookstylechoiceone of 7default

How big and bold the text looks

Switches the font between a small line, a headline, a title, a caption and monospaced or terminal looks.

  • default defaultsmall body text
  • headlinebold headline size
  • titlelarger bold title
  • captionsmall caption text
  • monobody text in a monospaced font
  • large-monolarger monospaced text, good for big numbers
  • terminala dark ANSI terminal view that keeps colors and columns
GlowglowRadiusnumber0–30 ptstep 10

A soft halo behind the words

Adds a blurred glow in the text color, 0 to 30 points wide; 0 turns it off.

Colortintcolor#FFFFFF

The color of the words and symbol

Recolors the text and the symbol in front of it.

Alignmentalignchoiceone of 3leading

Where the words sit across the label

Moves the text to the left edge, the middle or the right edge of the label.

  • leading defaulttext starts at the left edge
  • centertext is centered
  • trailingtext ends at the right edge
WeightfontWeightchoiceone of 9regular

How thick the letter strokes are

Makes the letters lighter or heavier, from ultra thin to black, on top of the chosen style.

  • ultraLighthairline strokes
  • thinvery slim strokes
  • lightslim strokes
  • regular defaultnormal strokes
  • mediumslightly heavier than normal
  • semiboldfirm, between medium and bold
  • boldheavy strokes
  • heavyvery heavy strokes
  • blackthe heaviest strokes
Look aheadforecastchoiceone of 2—

How fast the guess keeps moving

Moves the displayed number by this much every second after the last real reading, from -1000 to 1000.

  • countdownthe value is a time and the label counts down to it
  • reachthe value is guessed to move toward a target number until the next real reading
Unitunittext—

The measurement the number is in

Converts a numeric value to the phone's own units, so celsius shows as degrees Fahrenheit in the US; text is shown as sent.

Scrolling logscrollableon / offfalse (off)

Turns the label into a log you can scroll

Gives the label a fixed height that scrolls and stays on the newest line.

Number formatformatValuetext—

How the value is written out

Shows the value as a rounded number, a percent, a duration, a size, a date or a time since, instead of the raw text.

Text before any valueplaceholdertext—

What to say before there is a date

Shows this text (Never by default) on a time-since or date label that has no date yet.

Words for valuesvalueMapobject—

Show different words for different values

Replaces a raw incoming value such as 61 with the words you pick, with default catching the rest.

Symbols for valuesiconMapobject—

Show different symbols for different values

Swaps the symbol in front of the text to match the incoming value.

Colors for valuescolorMapobject—

Show different colors for different values

Recolors the text to match the incoming value, for example green for running.

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
Subtitle colortheme.secondaryColorcolor—

The breathing room inside the label

Pushes the text in from the edges by 0 to 24 points.

Corner roundnesstheme.cornerRadiusnumber0–30 ptstep 112

The fill behind the text

Colors the line drawn around the label.

Border thicknesstheme.borderWidthnumber0–5 ptstep 0.51

The main color of the words

Sets the color the text is drawn in when no Color is chosen.

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

the text to show (a number is shown with its unit and format)

the text is replaced by the new value, through the value map, unit and format if set; before the first value the static text shows

Example: Sample A

Sample

The placeholder value the editor shows before real data arrives.

  • Sample A then Sample B

Examples

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

Time since (plant watering)

Shows a remembered date as a time-since readout that advances by itself; with no date yet it says the placeholder.

JSON 3 lines
{ "type": "label", "id": "fern-watered", "label": "Fern — last watered", "icon": "leaf.fill",
  "formatValue": "relative:day", "placeholder": "Not watered yet",
  "sync": [{ "method": "meshsocket", "event": "broadcast", "filter": { "msg_type": "fern" }, "valuePath": "lastWatered" }] }

Open in CAR-TER

Text: Time since (plant watering)
Rendered by the app

Static info label

Shows fixed text with no sync; the simplest label, it reads exactly as written.

JSON 7 lines
{
  "type": "label",
  "id": "temp-display",
  "position": [0, 0],
  "span": [1, 2],
  "text": "Current: 72°F"
}

Open in CAR-TER

Text: Static info label
Rendered by the app

Synced label with icon

Shows a live value behind a small gray symbol; the dash stays until the first value arrives.

JSON 10 lines
{
  "type": "label",
  "id": "track-artist",
  "position": [1, 2],
  "span": [1, 2],
  "text": "—",
  "icon": "person.fill",
  "tint": "#AAAAAA",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "player_state" }, "valuePath": "artist" }]
}

Open in CAR-TER

Text: Synced label with icon
Rendered by the app

Name with a subtitle

Shows a name with a smaller gray line under it, two compact lines in one label; in a list row the second line comes from the item.

JSON 14 lines
{
  "type": "label",
  "id": "pkg",
  "position": [
    0,
    1
  ],
  "span": [
    1,
    2
  ],
  "text": "{{item.name}}",
  "subtitle": "{{item.version}} · {{item.author}}"
}

Open in CAR-TER

Wrapping text

Shows a long description over up to three lines instead of cutting it off after one.

JSON 14 lines
{
  "type": "label",
  "id": "blurb",
  "position": [
    0,
    0
  ],
  "span": [
    2,
    4
  ],
  "text": "A longer description that should wrap onto several lines.",
  "lines": 3
}

Open in CAR-TER

Headline style

Shows a live value in the bold headline size, useful for a title that changes.

JSON 9 lines
{
  "type": "label",
  "id": "track-title",
  "position": [0, 2],
  "span": [1, 2],
  "text": "No Track",
  "style": "headline",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "player_state" }, "valuePath": "title" }]
}

Open in CAR-TER

Text: Headline style
Rendered by the app

Terminal snapshot (live pane)

Shows a captured shell pane as a scrolling dark terminal with colors kept, pinned to the newest line.

JSON 11 lines
{
  "type": "label",
  "id": "pane-snapshot",
  "position": [1, 0],
  "span": [5, 4],
  "style": "terminal",
  "scrollable": true,
  "controlHeight": 360,
  "text": "(waiting for pane…)",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "snapshot" }, "valuePath": "text" }]
}

Open in CAR-TER

Text: Terminal snapshot (live pane)
Rendered by the app

Weather code → words, no server

Turns a numeric weather code into centered words with a matching symbol, and an em dash for any unknown code.

JSON 12 lines
{
  "type": "label",
  "id": "wx-text",
  "position": [0, 0],
  "span": [1, 2],
  "text": "…",
  "style": "headline",
  "align": "center",
  "valueMap": { "0": "Clear", "1": "Mainly clear", "2": "Partly cloudy", "3": "Overcast", "45": "Fog", "51": "Drizzle", "61": "Rain", "71": "Snow", "80": "Showers", "95": "Thunderstorm", "default": "—" },
  "iconMap": { "0": "sun.max.fill", "1": "sun.max.fill", "2": "cloud.sun.fill", "3": "cloud.fill", "45": "cloud.fog.fill", "51": "cloud.drizzle.fill", "61": "cloud.rain.fill", "71": "cloud.snow.fill", "80": "cloud.heavyrain.fill", "95": "cloud.bolt.rain.fill" },
  "sync": [{ "method": "http", "url": "https://api.open-meteo.com/v1/forecast?latitude=42.36&longitude=-71.06&current=weather_code", "interval": 900, "valuePath": "current.weather_code" }]
}

Open in CAR-TER

Text: Weather code → words, no server
Rendered by the app

Boolean state as words and colour

Shows true as green Running and false as gray Stopped, with a matching symbol for each.

JSON 12 lines
{
  "type": "label",
  "id": "pump-state",
  "position": [1, 0],
  "span": [1, 2],
  "text": "—",
  "align": "center",
  "valueMap": { "true": "Running", "false": "Stopped" },
  "iconMap": { "true": "bolt.fill", "false": "bolt.slash" },
  "colorMap": { "true": "#30D158", "false": "#8E8E93" },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "pump" }, "valuePath": "running" }]
}

Open in CAR-TER

Text: Boolean state as words and colour
Rendered by the app

Number with a unit

Shows a Celsius reading converted to the phone's units, so a US phone reads it in degrees Fahrenheit.

JSON 2 lines
{ "type": "label", "id": "outside-temp", "position": [0, 0], "span": [1, 2], "text": "…", "unit": "celsius", "formatValue": "decimal", "style": "large-mono", "align": "center",
  "sync": [{ "method": "http", "url": "https://api.open-meteo.com/v1/forecast?latitude=42.36&longitude=-71.06&current=temperature_2m", "interval": 900, "valuePath": "current.temperature_2m" }] }

Open in CAR-TER

Text: Number with a unit
Rendered by the app

Fixed decimals and percent

Shows a battery fraction as a whole percent; swap the format for decimal:2 to get two decimal places instead.

JSON 2 lines
{ "type": "label", "id": "battery", "position": [0, 2], "span": [1, 2], "text": "—", "icon": "battery.75percent", "formatValue": "percent",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "power" }, "valuePath": "battery" }] }

Open in CAR-TER

Text: Fixed decimals and percent
Rendered by the app

Date and time

Shows a stored instant as a readable date with the time, such as Sep 26, 2026 at 2:03 PM, in the phone's language.

JSON 2 lines
{ "type": "label", "id": "last-backup", "position": [1, 0], "span": [1, 2], "text": "—", "formatValue": "date:time", "placeholder": "No backup yet",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "backup" }, "valuePath": "finishedAt" }] }

Open in CAR-TER

Text: Date and time
Rendered by the app

Big centered number (look presets)

Shows a number in the large monospaced style, centered and heavy, the way the Big number look does.

JSON 2 lines
{ "type": "label", "id": "big-count", "position": [1, 2], "span": [1, 2], "text": "0", "style": "large-mono", "align": "center", "fontWeight": "bold", "tint": "#30D158",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "counter" }, "valuePath": "count" }] }

Open in CAR-TER

Text: Big centered number (look presets)
Rendered by the app

Quiet caption

Shows small, light text for a footnote that should not compete with the readings around it.

JSON 17 lines
{
  "type": "label",
  "id": "footnote",
  "position": [
    2,
    0
  ],
  "span": [
    1,
    4
  ],
  "text": "Updated every 15 minutes",
  "style": "caption",
  "fontWeight": "light",
  "tint": "#8E8E93",
  "align": "trailing"
}

Open in CAR-TER

Text: Quiet caption
Rendered by the app

Glowing readout

Shows a value with a soft 8-point halo in its own color, for a lit-display feel.

JSON 17 lines
{
  "type": "label",
  "id": "glow-temp",
  "position": [
    2,
    4
  ],
  "span": [
    1,
    2
  ],
  "text": "72°",
  "style": "title",
  "tint": "#0A84FF",
  "glowRadius": 8,
  "align": "center"
}

Open in CAR-TER

Text: Glowing readout
Rendered by the app

Countdown to a time

Shows the time left until a moment that arrives as a time value, ticking down on its own between readings.

JSON 2 lines
{ "type": "label", "id": "next-bus", "position": [3, 0], "span": [1, 2], "text": "—", "icon": "bus", "forecast": "countdown", "formatValue": "time",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "bus" }, "valuePath": "arrivesAt" }] }

Open in CAR-TER

Text: Countdown to a time
Rendered by the app

Expected to reach a number

Shows a charge percent that keeps climbing toward 100 at the time another control reports, marked as about, until a real reading replaces it.

JSON 2 lines
{ "type": "label", "id": "ev-charge", "position": [3, 2], "span": [1, 2], "text": "—", "formatValue": "percent", "forecast": "reach", "forecastTarget": 100, "forecastTimeFrom": "ev-done-at",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "ev" }, "valuePath": "charge" }] }

Open in CAR-TER

Text: Expected to reach a number
Rendered by the app

Drifting by a rate

Shows a tank level that keeps falling by 0.05 per second from the last reading when no end time is known.

JSON 2 lines
{ "type": "label", "id": "tank-level", "position": [3, 4], "span": [1, 2], "text": "—", "formatValue": "decimal:1", "forecast": "reach", "forecastRate": -0.05,
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "tank" }, "valuePath": "level" }] }

Open in CAR-TER

Text: Drifting by a rate
Rendered by the app

Words for a code

Shows a device state code as plain words, with the default catching anything unexpected.

JSON 2 lines
{ "type": "label", "id": "door-state", "position": [4, 0], "span": [1, 2], "text": "—", "valueMap": { "0": "Closed", "1": "Open", "default": "Unknown" }, "colorMap": { "1": "#FF9F0A" },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "door" }, "valuePath": "state" }] }

Open in CAR-TER

Text: Words for a code
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 “Time since (plant watering)” on your phone.

    carterkit demo label --example 'Time since (plant watering)'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Value maps

A feed you don't control emits codes — a WMO weather code, a device state, an alarm level — and the label should read as words, not 61. valueMap, iconMap, and colorMap say what each value looks like, declaratively:

"valueMap": { "0": "Clear", "3": "Overcast", "61": "Rain", "default": "—" },
"iconMap":  { "0": "sun.max.fill", "3": "cloud.fill", "61": "cloud.rain.fill" },
"colorMap": { "61": "#0A84FF" }
  • Keys match the stringified value, so 0, "0", true, and "rain" all work from the same map. true/false also match yes/no/on/off/1/0, and a number matches whether it arrives as 61 or 61.00. Key lookup falls back to a case-insensitive match.
  • "default" is the catch-all for any value with no entry.
  • No match and no "default" ⇒ the label degrades gracefully: the raw value for valueMap, the control's own icon/tint for iconMap/colorMap. It never blanks out.
  • A valueMap hit is the text as written — formatValue is not applied on top.
  • The maps apply to the synced value; before the first sync the static text placeholder still shows.

The same three fields work on Background, where valueMap maps to an image URL.

Format Values

Value Output Example
"decimal" "72" or "3.5" Rounds to integer
"decimal:N" "3.14" Fixed N decimal places (e.g., "decimal:2")
"percent" "80%" Integer percentage
"time" "3:45" Minutes:seconds from total seconds
"duration" "1h 23m" Human-readable duration from seconds
"bytes" "1.2 GB" Auto-scaled byte units
"bps" "54 Mbps" Auto-scaled bits-per-second
"suffix:X" "72°F" Append custom suffix (e.g., "suffix:°F")
"relative" "4 days ago", "in 2 hours" A date shown as time-since / time-until — see Relative dates
"relative:day" "Today", "Yesterday", "4 days ago" Whole local calendar days
"date" "Sep 26, 2026" A date shown as the date itself (locale medium style); no date → placeholder
"date:time" "Sep 26, 2026 at 2:03 PM" The date and the time
"none" (hidden) No value display

Look formats

In the editor's Look card, Text offers four Format chips, declared in this doc's lookFormats frontmatter: Plain (no formatValue), Number ("decimal"), Last time ("relative:day") and Date ("date"). A chip only writes formatValue; everything else stays as authored.

"Last time" is a Text format, not a separate control: the Add sheet offers one Text choice, and showing a remembered time on a Text (Wire › a time value) picks the Last time format for it, so the Look card shows that chip selected.

Relative dates

formatValue: "relative" and "relative:day" turn a label bound to a date into a time-since readout that advances on its own — "Fern: last watered 4 days ago" becomes "5 days ago" tomorrow with no server, poll or data event.

  • Accepted values: an ISO-8601 instant ("2026-09-22T08:15:00Z", fractional seconds and offsets allowed — the {{now}} encoding), a date-only string ("2026-09-22", read as that day in the device's local calendar), or an epoch number (seconds; milliseconds when larger than 10^11).
  • relative picks the largest sensible unit: "Now" (under a minute), "5 minutes ago", "In 2 hours", "4 days ago".
  • relative:day counts whole local calendar days: "Today", "Yesterday", "Tomorrow", "4 days ago", "In 2 days". Something done at 23:30 reads "Yesterday" at 00:30, whatever the UTC date says.
  • No date yet (absent, null, empty, unparseable, or epoch 0) shows placeholder — "Never" by default, localized. It is never blank, "0" or a 1970 date.
  • Before the first sync, a static text holding a date is formatted the same way.
  • Text is localized (e.g. German "Vor 4 Tagen", "Gestern").
  • The label refreshes itself once a minute with its own timer; nothing is written back to the control's value. Widget slots bound to the same control show the same text, refreshed whenever the widget reloads its timeline.

Styles

Value Font
"default" .subheadline
"headline" .headline.bold
"title" .title2.bold
"caption" .caption
"mono" .subheadline monospaced
"large-mono" .title3 monospaced medium
"terminal" Monospaced ANSI terminal — see Terminal style

Terminal style

style: "terminal" (and, as a shortcut, mono/large-mono + scrollable) renders the text as a real terminal instead of a plain mono label — purpose-built for piping a captured shell/tmux pane to the phone:

  • ANSI styling — colour (16 / 256 / truecolor), bold, dim, italic, underline, and reverse are parsed from the escape codes and rendered. Plain text (no escapes) renders normally.
  • Pane-matched scaling — the font auto-scales so the source's column width exactly fills the view, so box-drawing and ASCII line up like the real pane. If a server prepends a CSI 8;rows;cols t size report, that column count is used; otherwise the widest line is.
  • Dark backdrop — drawn on its own dark background (independent of the app theme) so ANSI colours have the contrast they were designed for.
  • Pinch to zoom — pinch to scale the text past the fitted size; double-tap snaps back to fit. Content wider/taller than the view scrolls both ways.
  • Sizing — set controlHeight for the on-screen height; fontSize caps the fitted font before zoom. Keeps the latest line in view and auto-scrolls on update.

Feed it like any synced label (a .string value); see the tmux-bridge server for a complete example.

Behavior

  • When synced, the text field serves as a placeholder until the first sync value arrives
  • Text updates animate with a smooth numeric content transition
  • Labels have no action — they are display-only
  • valueMap/iconMap/colorMap translate the synced value on the way to the screen — see Value maps

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