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
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
Field
Type
Default
What it does
Titlelabel
text
—
The heading above the table
Shows this text as the header line on the card; empty leaves the header blank.
Rowsrows
list
—
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.
LayoutkeyValueStyle
choiceone of 3
rows
Whether readings are lines, pills or cards
Redraws the same readings as a list of lines, wrapping pills or small cards.
rowsdefaultone 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
Columnscolumns
number1–4step 1
1
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.
SortedsortKeys
on / off
false(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 emptyhideEmpty
on / off
true(on)
Drop readings that have nothing to show
When on rows with no value disappear; off keeps them in place with a dash.
Row limitmaxRows
number0–200step 1
0
The most readings the table will show
Stops drawing after this many rows (0 to 200); 0 shows them all.
Number formatformat
text
—
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 colorscolorMap
object
—
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.
Colortint
color
—
The accent for the readings
Colors the values that have no status color; the key names follow it unless they have their own.
Key colorkeyTint
color
—
The shade of the names on the left
Colors the names of the readings; unset uses the softer theme text color.
Value colorvalueTint
color
—
The shade of the readings themselves
Colors the values that have no status color; unset follows the accent color.
Title shownhideLabel
on / off
false(off)
Whether the heading is shown
When on the header line is removed and the table moves up to fill the space.
BackgroundhideBackground
on / off
false(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
Field
Type
Default
What it does
Text colortheme.foregroundColor
color
#FFFFFF
The main text shade
Colors the values and header when no tint is set.
Soft text colortheme.secondaryColor
color
#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
Sends
When
Type
What it sends
When you tap a rowrow
tap
json
the tapped row's raw value
Only when an action is set; with no action the table is read-only
Example: 1
Receives
Receives
Takes
From
Type
What it does
itemsshow
hub, mqtt, http, store
json
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.
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.
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 thicknessformatValue 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