Guide / Controls / Readouts

Details

Labeled readings from one object

When to use it. Renders a JSON object as labeled rows. It is the sibling of Card padding, which needs an *array* — and objects are what REST endpoints, MQTT retained topics and status broadcasts actually return, so this is the control most telemetry lands in.

Type
keyValue
Also titled
Key–Value
Default size
3 rows × 4 columns
Symbol
tablecells
Docs
Docs complete
Search for it as
  • details
  • key value
  • properties
  • fields
  • info
  • readings
Details: Device health over MeshSocket
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Titlelabeltext—

The heading above the table

Shows this text as the header line on the card; empty leaves the header blank.

Rowsrowslist—

Which readings to show, in what order, and how each is labeled

Limits the table to the listed keys in that order with their own names, icons and units; leave it out to show every key.

LayoutkeyValueStylechoiceone of 3rows

Whether readings are lines, pills or cards

Redraws the same readings as a list of lines, wrapping pills or small cards.

  • rows defaultone line per reading with the name on the left and the value on the right
  • chipsshort wrapping pills that are good for scanning many values
  • gridsmall cards that suit a handful of headline numbers
Columnscolumnsnumber1–4step 11

How many readings sit side by side

Sets 1 to 4 columns of rows or cards across the control; the grid layout starts at 2.

SortedsortKeyson / offfalse (off)

Put the readings in A to Z order

When on the readings are listed alphabetically by key; off keeps the order the feed sent.

Hide emptyhideEmptyon / offtrue (on)

Drop readings that have nothing to show

When on rows with no value disappear; off keeps them in place with a dash.

Row limitmaxRowsnumber0–200step 10

The most readings the table will show

Stops drawing after this many rows (0 to 200); 0 shows them all.

Number formatformattext—

How plain numbers are written

Prints every number in rows without their own format as a percent, duration, size or with a unit suffix such as °C.

Status colorscolorMapobject—

Colors that follow what a value says

Tints a value with the color listed for it (for example true green and false red); unlisted values use the normal value color.

Colortintcolor—

The accent for the readings

Colors the values that have no status color; the key names follow it unless they have their own.

Key colorkeyTintcolor—

The shade of the names on the left

Colors the names of the readings; unset uses the softer theme text color.

Value colorvalueTintcolor—

The shade of the readings themselves

Colors the values that have no status color; unset follows the accent color.

Title shownhideLabelon / offfalse (off)

Whether the heading is shown

When on the header line is removed and the table moves up to fill the space.

BackgroundhideBackgroundon / offfalse (off)

The card behind the table

When on the fill and border are removed so the readings sit straight on the page.

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
Text colortheme.foregroundColorcolor#FFFFFF

The main text shade

Colors the values and header when no tint is set.

Soft text colortheme.secondaryColorcolor#FFFFFF99

How heavy the outline is

Draws the card's edge line 0 to 5 points thick; 0 removes it.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you tap a rowrowtapjson

the tapped row's raw value

Only when an action is set; with no action the table is read-only

Example: 1

Receives

Receives
TakesFromTypeWhat it does
itemsshowhub, mqtt, http, storejson

one object whose keys become labeled rows (or a list of key and value pairs to fix the order)

every push replaces the whole table, so send the full object each time

Example: {"Item 1": 1, "Item 2": 2}

Sample

The placeholder value the editor shows before real data arrives.

  • {"Item 1": 1, "Item 2": 2, "Item 3": 3} then {"Item 1": 3, "Item 2": 2, "Item 3": 1}

Examples

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

Device health over MeshSocket

Shows a Pi's live stats as labeled rows with icons, and tints the link value green or red by its state.

JSON 24 lines
{
  "type": "keyValue",
  "id": "health",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Pi Health",
  "rows": [
    { "key": "cpu", "label": "CPU", "format": "percent", "icon": "cpu" },
    { "key": "temp", "label": "Temp", "format": "suffix:°C", "icon": "thermometer.medium" },
    { "key": "uptime", "label": "Uptime", "format": "duration", "icon": "clock" },
    { "key": "ip", "label": "IP", "icon": "network" },
    { "key": "online", "label": "Link", "icon": "antenna.radiowaves.left.and.right" }
  ],
  "colorMap": { "true": "#34C759", "false": "#FF3B30" },
  "sync": [
    {
      "method": "meshsocket",
      "type": "listen",
      "event": "broadcast",
      "filter": { "msg_type": "health" },
      "valuePath": "stats"
    }
  ]
}

Open in CAR-TER

Details: Device health over MeshSocket
Rendered by the app

Open-Meteo "current" — a zero-server dashboard

Shows current weather as a two-column grid of cards, each with a unit, read straight from a polled web source.

JSON 22 lines
{
  "type": "keyValue",
  "id": "weather-now",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Right Now",
  "keyValueStyle": "grid",
  "columns": 2,
  "rows": [
    { "key": "temperature_2m", "label": "Air", "unit": "°C" },
    { "key": "relative_humidity_2m", "label": "Humidity", "unit": "%" },
    { "key": "wind_speed_10m", "label": "Wind", "unit": "km/h" },
    { "key": "is_day", "label": "Daylight" }
  ],
  "sync": [
    {
      "method": "http",
      "source": "open-meteo",
      "valuePath": "current"
    }
  ]
}

See Data Sources for the polled-HTTP source block this reads from.

Details: Open-Meteo "current" — a zero-server dashboard
Rendered by the app

Drill-down chips

Shows every key as an A to Z wrapping pill (at most 12); tapping a pill sends that key and its value to an agent.

JSON 20 lines
{
  "type": "keyValue",
  "id": "env",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Environment",
  "keyValueStyle": "chips",
  "sortKeys": true,
  "maxRows": 12,
  "action": {
    "method": "meshsocket",
    "mode": "broadcast",
    "event": "route_msg",
    "payload": {
      "target_id": "agent",
      "type": "inspect",
      "payload": { "field": "{{key}}", "was": "{{value}}" }
    }
  }
}

Open in CAR-TER

Details: Drill-down chips
Rendered by the app

Plain details with a default number format

Shows an object with no rows list, so every key appears, with all numbers written as percentages and a custom accent color for values.

JSON 12 lines
{
  "type": "keyValue",
  "id": "disk",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Disk",
  "format": "percent",
  "tint": "#5AC8FA",
  "sync": [
    { "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "disk" }, "valuePath": "usage" }
  ]
}

Open in CAR-TER

Details: Plain details with a default number format
Rendered by the app

Two-column rows with their own key and value colors

Shows rows in two columns with the names in grey and the values in orange, keeping empty readings visible as dashes.

JSON 12 lines
{
  "type": "keyValue",
  "id": "pairs",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Pairs",
  "keyValueStyle": "rows",
  "columns": 2,
  "hideEmpty": false,
  "keyTint": "#8E8E93",
  "valueTint": "#FF9F0A"
}

Open in CAR-TER

Details: Two-column rows with their own key and value colors
Rendered by the app

Bare table without a title or card

Shows the readings straight on the page with no header and no card surface, for a quiet inline look.

JSON 8 lines
{
  "type": "keyValue",
  "id": "bare",
  "position": [0, 0],
  "span": [3, 4],
  "hideLabel": true,
  "hideBackground": true
}

Open in CAR-TER

Details: Bare table without a title or card
Rendered by the app

Feed that pins its own order

Shows how an array of key and value pairs keeps the feed's order; the value [{ "key": "b", "value": 2 }, { "key": "a", "value": 1 }] prints b before a.

JSON 8 lines
{
  "type": "keyValue",
  "id": "ordered",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Ordered",
  "sortKeys": false
}

Open in CAR-TER

Details: Feed that pins its own order
Rendered by the app

Theme override

Shows a squarer card with a thicker orange border using the control's theme fields.

JSON 8 lines
{
  "type": "keyValue",
  "id": "themed",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Themed",
  "theme": { "cornerRadius": 4, "borderWidth": 2, "borderColor": "#FF9F0A" }
}

Open in CAR-TER

Details: Theme override
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 “Device health over MeshSocket” on your phone.

    carterkit demo keyValue --example 'Device health over MeshSocket'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Data shape

The control's value is a JSON document, exactly like Axis bottom or Label color: point sync at the feed and let valuePath pick the sub-object.

{ "cpu": 41, "temp": 52.5, "uptime": 86400, "ip": "10.0.0.7", "online": true }

Two inbound shapes are accepted:

Shape When to use it
An object The normal case. Key order is the order the feed wrote it
An array of pairs — [{ "key": "cpu", "value": 41 }, …] A feed that wants to pin the order itself, or one with duplicate-ish names

Each push replaces the table (unlike Title or Color, which append). A server that wants a partial update should send the whole object back.

Values print by type: strings verbatim, numbers through the Border thickness formatValue vocabulary, booleans as ✓ Yes / ✗ No, and nested objects or arrays as compact JSON in a mono face — so a table never silently hides part of its own document. hideEmpty (on by default) drops nulls and empty strings, which is what keeps a sparse feed from drawing a column of dashes.

Rows

Without rows the table shows every key. With it, rows is both the whitelist and the order:

Key Type Description
key string The key to read. Dot paths work (properties.mag, geometry.coordinates.0), same as a Card padding column
label string Display name; defaults to a prettified key (cpu_temp → "Cpu Temp")
format string Number format for this row; overrides the control-level format
icon string Leading SF Symbol
unit string Appended after the value, space-separated. For a tight unit use format: "suffix:°C"

A key the document doesn't contain renders as —, or disappears entirely when hideEmpty is on.

Styles

keyTint and valueTint colour the key names and the values (a colorMap hit still wins for a value).

  • rows (default) — label left, value right. columns: 2 prints two pairs per line in a wide cell.
  • chips — wrapping pills. Best for a dozen short values you want to scan, not read in order.
  • grid — small cards, two across by default. Best for a handful of headline numbers.

Sizing

Rows scroll inside the control, so the cell never overflows — but a table crushed to one row is unreadable. In a 2-D grid give it a real rowSpan: [3, 4] fits about six pairs, [5, 4] about a dozen. See Grid Dimensions.

Tapping a row

Give the control an action and every row becomes a button, substituting {{key}} (the row's key, dot path and all) and {{value}} (its raw value). That turns a health table into a drill-down. With no action the table is read-only and VoiceOver reads it as text rather than as controls.

Behavior

  • Each push replaces the whole table; rows animate in and out
  • colorMap matches the stringified value (true, 41, "idle"), with a default entry as the catch-all — the same matcher Border thickness and Background use
  • Long values scale down before they truncate; structured values print as compact JSON
  • Rows scroll internally, so the control always fits its cell

Card padding · Border thickness · Sync · Data Sources · Toggle expand · Grid Dimensions

Generated from ControlDocs/key-value.md. Something unclear or missing? Tell me.