Guide / Controls / Readouts

Table

Rows of information

When to use it. A tabular data display that renders rows of structured data with configurable columns. Rows are populated via sync and can be formatted per column.

Type
list
Also titled
List
Default size
3 rows × 4 columns
Symbol
list.bullet
Docs
Docs complete
Search for it as
  • rows
  • table
  • items
  • entries
  • feed
  • menu
Table: Device status list
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Date formatformatValuetext—

How dates in the rows are written

Dates in columns without their own format show as e.g. 4 days ago (relative:day) or a calendar date; other text is unchanged.

Titlelabeltext—

The heading above the rows

Shows this text as the header line above the rows in the header text size.

ColumnslistColumnslist—

Which columns to show and how to display them

Sets the columns across each row: their order, header text and number or date format; with none, up to 3 columns are picked from the data.

Empty messageemptyTexttext—

What to show when there are no rows

Replaces the line shown when there are no rows, e.g. No books yet.

Header colortintcolor#FFFFFF

The color of the heading

Paints the header label in this color.

Hide the titlehideLabelon / offfalse (off)

Hide the heading line

Removes the header label so the rows start at the top of the card.

No background cardhideBackgroundon / offfalse (off)

Remove the card behind the rows

Drops the frosted card fill so the rows sit directly on the screen background.

Starting rowsdefaultValueobject[]—

Starting rows shown until new data arrives

After a tap writes locally, a pill naming the change appears for 3 seconds with an Undo button.

Load as you scrollpagingobject—

Load rows from the hub a page at a time as you scroll

Asks the hub for the first rows when the list appears and for more as you near the end, so a list of any length scrolls without the phone holding every row.

Rows per pagepaging.pageSizenumber5–200step 550

How many rows each request asks for

Asks the hub for this many rows at a time, e.g. 50; the next request goes out when you are half a page from the last row.

Page requestpaging.requestobject—

The message that asks the hub for rows

Sends this message for every page with the position, the page size and the search text filled in.

Reply typepaging.replyTypetext—

Which hub messages carry the rows

Takes rows only from hub messages of this type and leaves every other message alone.

Page inside the replypaging.replyPathtext—

Where the rows sit inside a reply

Reads the page from this part of each reply, e.g. result, instead of from the top of the message.

Rows keptpaging.windownumber20–5000step 50600

How many rows the phone keeps at once

Keeps at most this many rows around the ones on screen, e.g. 600, and asks the hub again for rows you scroll back to.

Search fieldpaging.queryFromtext—

The field whose text filters the rows

Sends that field's text as the search with every request, and starts the list over from the top when the text changes.

Row designitemTemplateobject—

Draw each row from controls instead of columns

Lays out each row as its own small grid of controls, e.g. a name, a version and a button, filled in from that row's data.

Row gapitemSpacingnumber0–64step 12

How far apart the rows sit

Opens up space between rows, so card-style rows stand apart from each other.

Row lookitemStylechoiceone of 2plain

Plain rows or a card per row

Gives every templated row a card of its own, styled by the template's theme, instead of lines inside one list card.

  • plain defaultrows sit inside the list's own card, as before
  • cardeach templated row is its own card, styled by the template group
Row layoutitemLayoutchoiceone of 2rows

One row per line, or cards side by side

Lays the templated rows out as a grid of cards, 2 or 3 to a line by the list's width, scrolling and loading as the rows do.

  • rows defaultone templated row per line, as before
  • gridtemplated rows as cards side by side, 2 or 3 columns by the list's width

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
Card paddingtheme.cardPaddingnumber0–32step 112

The color of the row text

Sets the outline thickness from 0 (none) to 5 points.

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 rowrowtapid

the tapped row's id

Only rows with a text id can be tapped; with no action set, a list bound to a My Data collection opens that row's entry sheet instead

Example: row-1

Receives

Receives
TakesFromTypeWhat it does
rowsshowhub, mqtt, http, storejson

a list of rows, each with the values for its columns and an optional id

rows are replaced by the new list, and the columns come from the rows' own keys unless you set them

Example: [{"id": "row-1", "name": "Item 1"}]

Sample

The placeholder value the editor shows before real data arrives.

  • [{"id": "row-1", "name": "Item 1", "detail": "Example 1"}, {"id": "row-2", "name": "Item 2", "detail": "Example 2"}, {"id": "row-3", "name": "Item 3", "detail": "Example 3"}] then [{"id": "row-1", "name": "Item 1", "detail": "Example 1"}, {"id": "row-2", "name": "Item 2", "detail": "Example 2"}, {"id": "row-3", "name": "Item 3", "detail": "Example 3"}, {"id": "row-4", "name": "Item 4", "detail": "Example 4"}]

Examples

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

Package cards that expand

Shows templated rows drawn as separate cards that each grow into a full-screen page. Intended effect: a scrolling column of package cards (icon, name, version, Install); tapping a card (anywhere but the Install button) or holding it grows that card to full screen with a bigger icon, the name beside it and the notes below.

JSON 29 lines
{
  "type": "list",
  "id": "packages",
  "position": [0, 0],
  "span": [6, 4],
  "hideBackground": true,
  "itemStyle": "card",
  "itemSpacing": 10,
  "itemTemplate": {
    "grid": { "columns": 4, "rows": 1 },
    "children": [
      { "type": "image", "id": "icon", "position": [0, 0], "systemName": "shippingbox" },
      { "type": "label", "id": "name", "position": [0, 1], "span": [1, 2], "text": "{{item.name}} {{item.version}}" },
      { "type": "button", "id": "install", "position": [0, 3], "label": "Install",
        "action": { "method": "meshsocket", "event": "install", "payload": { "id": "{{item.id}}" } } }
    ],
    "expand": {
      "title": "{{item.name}}",
      "grid": { "columns": 4, "rows": 5 },
      "children": [
        { "ref": "icon", "position": [0, 0], "span": [2, 2] },
        { "ref": "name", "position": [0, 2], "span": [1, 2] },
        { "ref": "install", "position": [1, 2], "span": [1, 2] },
        { "type": "label", "position": [2, 0], "span": [3, 4], "text": "{{item.notes}}" }
      ]
    }
  },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "packages" }, "valuePath": "items" }]
}

Open in CAR-TER

Card grid catalogue

Shows itemLayout: "grid" on a paged, searchable list with card rows. Intended effect: a catalogue of any size scrolls as a grid of cards, 2 to a line on a phone and 3 on an iPad, each card an icon over a name and a detail line; the hub sends 40 cards at a time as you scroll, typing in the gallery-search text input searches on the hub, and tapping a card sends its id.

JSON 27 lines
{
  "type": "list",
  "id": "gallery",
  "position": [1, 0],
  "span": [7, 4],
  "hideBackground": true,
  "itemStyle": "card",
  "itemLayout": "grid",
  "itemSpacing": 10,
  "emptyText": "Nothing matches",
  "action": { "method": "meshsocket", "event": "broadcast_request", "payload": { "msg_type": "item_open", "id": "{{value}}" } },
  "paging": {
    "pageSize": 40,
    "replyType": "gallery_page",
    "queryFrom": "gallery-search",
    "request": { "method": "meshsocket", "event": "broadcast_request",
                 "payload": { "msg_type": "gallery_pages", "offset": "{{offset}}", "limit": "{{limit}}",
                              "query": "{{query}}", "req": "{{req}}" } }
  },
  "itemTemplate": {
    "grid": { "columns": 2, "rows": 3 },
    "children": [
      { "type": "image", "id": "icon", "position": [0, 0], "span": [2, 2], "systemName": "shippingbox" },
      { "type": "label", "id": "name", "position": [2, 0], "span": [1, 2], "label": "{{item.detail}}", "text": "{{item.name}}" }
    ]
  }
}

Open in CAR-TER

The hub answers gallery_pages exactly as for rows (see Paging); the grid changes only how the cards are laid out.

Device status list

Shows a list fed live from a hub, with a number column. Intended effect: three columns of device name, status and ping that refresh whenever the hub broadcasts.

JSON 13 lines
{
  "type": "list",
  "id": "device-list",
  "position": [0, 0],
  "span": [2, 4],
  "label": "Connected Devices",
  "listColumns": [
    { "key": "name", "label": "Name" },
    { "key": "status", "label": "Status" },
    { "key": "latency", "label": "Ping", "format": "number" }
  ],
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "device_list" }, "valuePath": "devices" }]
}

Open in CAR-TER

The server broadcasts {"msg_type": "device_list", "devices": [{"name": "…", "status": "…", "latency": 12}, …]}; valuePath picks the row array out of the frame.

Table: Device status list
Rendered by the app

Nested feed rows (USGS GeoJSON, no server)

Shows dot-path column keys reading nested feed data. Intended effect: the last hour of earthquakes with magnitude, place and depth, refreshed every 5 minutes.

JSON 13 lines
{
  "type": "list",
  "id": "quake-list",
  "position": [2, 0],
  "span": [3, 4],
  "label": "Recent quakes",
  "listColumns": [
    { "key": "properties.mag", "label": "M", "format": "number" },
    { "key": "properties.place", "label": "Place" },
    { "key": "geometry.coordinates.2", "label": "Depth", "format": "number" }
  ],
  "sync": [{ "method": "http", "url": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson", "interval": 300, "valuePath": "features" }]
}

Open in CAR-TER

valuePath picks the row array out of the document; each column key then reaches into that row.

Table: Nested feed rows (USGS GeoJSON, no server)
Rendered by the app

Last-time look with starting rows

Shows the Last time look (formatValue: "relative:day") together with seed rows, a custom empty message and a hidden title. Intended effect: rows appear at once with dates like "4 days ago", and show "Nothing watered yet" if the data is cleared.

JSON 18 lines
{
  "type": "list",
  "id": "watering-log",
  "position": [0, 4],
  "span": [2, 3],
  "label": "Watering",
  "hideLabel": true,
  "formatValue": "relative:day",
  "emptyText": "Nothing watered yet",
  "listColumns": [
    { "key": "plant", "label": "Plant" },
    { "key": "when", "label": "Last watered" }
  ],
  "defaultValue": [
    { "plant": "Fern", "when": "2026-10-30" },
    { "plant": "Basil", "when": "2026-11-02" }
  ]
}

Open in CAR-TER

The Plain look leaves formatValue unset, and the Date look sets it to "date" so the same column shows a calendar date; the JSON is otherwise identical. A per-column format always wins over formatValue.

Table: Last-time look with starting rows
Rendered by the app

Tap a row to tick it (local store)

Shows a row tap bound to a local collection, with the confirmation pill. Intended effect: tapping a task marks it done, a pill with Undo appears for 3 seconds, and the row updates.

JSON 11 lines
{
  "type": "list",
  "id": "todo-list",
  "position": [2, 4],
  "span": [3, 4],
  "label": "To do",
  "confirm": true,
  "hideBackground": true,
  "action": { "method": "local", "op": "update", "collection": "items", "id": "{{value}}", "set": { "done": true } },
  "sync": [{ "method": "local", "collection": "items" }]
}
Table: Tap a row to tick it (local store)
Rendered by the app

Tap a row to select it

Shows the select binding that moves the selection cursor. Intended effect: tapping a book fills every control bound with "where": {"id": "{{selected}}"} with that book, so a form elsewhere can edit it.

JSON 9 lines
{
  "type": "list",
  "id": "book-list",
  "position": [0, 8],
  "span": [3, 4],
  "label": "Books",
  "action": { "method": "local", "op": "select", "collection": "books", "id": "{{value}}" },
  "sync": [{ "method": "local", "collection": "books" }]
}
Table: Tap a row to select it
Rendered by the app

Paged catalogue with a row design

Shows paging with a search field and an itemTemplate. Intended effect: a catalogue of any size scrolls with rows of name, detail and version, the hub sends 50 rows at a time, typing in the catalogue-search text input searches on the hub, and tapping a row sends its id.

JSON 24 lines
{
  "type": "list",
  "id": "catalogue",
  "position": [1, 0],
  "span": [7, 4],
  "label": "Catalogue",
  "emptyText": "Nothing matches",
  "action": { "method": "meshsocket", "event": "broadcast_request", "payload": { "msg_type": "item_open", "id": "{{value}}" } },
  "paging": {
    "pageSize": 50,
    "replyType": "catalogue_page",
    "queryFrom": "catalogue-search",
    "request": { "method": "meshsocket", "event": "broadcast_request",
                 "payload": { "msg_type": "catalogue_pages", "offset": "{{offset}}", "limit": "{{limit}}",
                              "cursor": "{{cursor}}", "query": "{{query}}", "req": "{{req}}" } }
  },
  "itemTemplate": {
    "grid": { "columns": 4, "rows": 1 },
    "children": [
      { "type": "label", "id": "name", "position": [0, 0], "span": [1, 3], "label": "{{item.detail}}", "text": "{{item.name}}" },
      { "type": "label", "id": "version", "position": [0, 3], "label": "Version", "text": "{{item.version}}" }
    ]
  }
}

Open in CAR-TER

The hub answers catalogue_pages with {"msg_type": "catalogue_page", "req": "<the req>", "items": [...], "total": 48211, "more": true}. A hub that wraps its replies, like {"msg_type": "daemon-reply", "req": "…", "result": {"rows": [...], "offset": 0, "more": true}}, sets "replyType": "daemon-reply" and "replyPath": "result".

The list has no look that switches it to another control type, and no long-press or detail view.

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 status list” on your phone.

    carterkit demo list --example 'Device status list'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Column keys

A key is looked up flat on the row first, so "key": "name" reads row.name and a row whose field name genuinely contains a dot still works.

If there's no flat match and the key contains dots, it's walked as a dot path:

  • "properties.title" → row.properties.title
  • "geometry.coordinates.0" → an integer segment indexes an array

That's what makes a nested public feed usable without a server in between: rows from a GeoJSON features[] keep their data under properties, and a path key reads it directly. A key that resolves to nothing renders as —.

Columns when none are given

A list with no listColumns (or an empty array) still shows its rows:

  • Bound to a Local Store (a method: "local" sync that neither groups nor aggregates): the collection's fields, as declared in the layout's sources (or by the running store, for a shared collection) — the field that names a row first, then the field it sorts by, then the rest in declared order (order, else by name). Labels are the fields' friendly names, numbers format as numbers, and raw-data (json) fields are left out. At most 3 columns.
  • Anything else (a grouped store binding, a web or hub feed): the rows' own keys, plain values by name first. At most 3 columns.

An empty store shows the empty-state line (emptyText, else "No <label> yet", else "No rows yet"), never a configuration error. Write listColumns to choose the columns, their order, labels and formats yourself; the editor writes them when it binds a list to a store.

Row taps

With an action, each row whose data carries an id becomes tappable and fires the action with {{value}} = that row's id. Rows from a Local Store binding always carry one, so a checklist ticks the tapped row with {"method": "local", "op": "update", "collection": "items", "id": "{{value}}", "set": {"done": true}} or removes it with op: "delete". To edit a row elsewhere on the screen, select it: {"method": "local", "op": "select", "collection": "books", "id": "{{value}}"} moves the selection cursor, and every control bound with "where": {"id": "{{selected}}"} refills with the tapped row. Rows without an id aren't tappable. Without an action the list stays read-only.

Paging

A list with paging asks its hub for rows a page at a time instead of holding the whole set, so a catalogue of tens of thousands of rows scrolls and searches smoothly. Its sync is not needed (rows come from the replies).

Requests. The list sends paging.request (a meshsocket action, normally a broadcast_request) when it first appears, and again when the user is half a page from the last loaded row. Its payload is filled in with:

Token Value
{{offset}} Index of the first row asked for (0 for the first page)
{{limit}} pageSize
{{cursor}} The cursor the hub sent with the page that ended at {{offset}}; null for the first page and for hubs that page by offset
{{query}} The search text ("" for none)
{{req}} A request id, unique per request

An exact token keeps its type ("offset": "{{offset}}" sends a number). A request with no reply after 8 seconds is sent again while the list is on screen.

Replies. The hub answers with a broadcast whose msg_type is paging.replyType. The page is the frame itself, or the object paging.replyPath names in it:

{ "msg_type": "catalogue_page", "req": "…", "items": [{ "id": "a1", "name": "…" }],
  "cursor": "…", "total": 48211, "more": true, "offset": 0, "query": "" }
  • items (or rows): the rows, in order, from offset. Required; a frame of this type without them is not a page (an error reply, another method's reply) and is ignored.
  • req: echo {{req}} (on the page or on the frame). With it, only the reply to a request still waiting is taken: a reply to an older search, or to another list sharing the replyType, is dropped. Without it, a page whose query differs from the current search is dropped, and the page goes to the oldest waiting request (or to offset, when echoed).
  • offset: where the rows go; default, the requested {{offset}}.
  • The end of the list is the first of: more: false; total reached; a cursor of null; none of these and fewer rows than {{limit}}. An empty page ends the list where it starts. total also tells VoiceOver how many rows there are.

Search. paging.queryFrom names a text input (a search field) in the layout. When its text changes, the list waits 250 ms without typing, then drops its rows and asks for the first page of the new search; the hub does the matching.

Window. The phone keeps at most paging.window rows (default 600) around the rows on screen. Rows far away are let go but keep their place, so the scroll position holds; when the user scrolls back to one, the list asks again for the page that held it (with that page's {{cursor}} and {{offset}}). A loading row shows while a page is on its way, the row count at the end, and emptyText when the search matches nothing. Row taps send the row id as usual (see Row taps).

The rows of a paged list live only on the phone for the layout on screen: switching tabs keeps them; a new connection or a layout change starts over.

Item templates

itemTemplate draws every row from controls instead of columns. It is a group definition (Extensions): a grid (default 4 columns × 1 row, 56 pt rows) and children placed on it; id and position may be left out. In the children's text, values, images, colors and action payloads, {{item.<field>}} is replaced from the row (a dot path reaches nested fields: {{item.meta.author}}), and an exact token keeps its type, so "defaultValue": "{{item.percent}}" feeds a gauge a number.

  • The row is the template's grid: one row of a 4-column grid is 56 pt tall. Set the grid's rowHeight to "auto" (rowHeight) and rows take their content's height instead, so a one-row card (icon, a label with a subtitle, a button) stays compact.
  • Children read the row, not live values: each shows what its fields and defaultValue say for that row; inputs in a row don't keep what is typed. Buttons fire their actions, with the row's fields already in the payload and {{value}} left for the tap.
  • A tap elsewhere on the row sends the row id through the list's action, as for column rows.
  • Ids are scoped to the row (<id>@<row id>), so they need not be unique in the layout. A child that doesn't decode once filled in (a text field where a number belongs) is left out of that row.
  • Text from the row is shown as written but never becomes a token itself ({{ in a row's data can't pull in a secret).

Without itemTemplate, rows are columns (listColumns), paged or not.

Card rows

With "itemStyle": "card" every templated row is a container of its own: the template group's card (the theme's surface, corners and border, or the template's own theme), padded like any group, instead of a line inside the list's card. Turn the list's own card off with "hideBackground": true and set an itemSpacing so the cards stand apart. A template with "hideBackground": true draws no card even here. Placeholder rows of a paged list take the card's height too.

Expanding a row

An expand block on the itemTemplate (Expand) lets each row grow, from where it sits, into a full-screen (or sheet) container with a corner close. Its {"ref": …} entries name the template's child ids and move that row's own controls to new cells; its other entries are controls only the expanded row has. {{item.<field>}} is filled in from the row in all of them and in title. The row's tap still sends its id; a row with an expand opens it on a tap no child claims (trigger tap, the default) or a hold. The expanded row shows the row as it was when opened.

Card grid

With "itemLayout": "grid" the templated rows sit side by side as cards instead of one per line, in as many columns as keep every card at least 150 pt wide, at most 3: a list as wide as a phone screen gets 2, a wider one (an iPad, a phone in landscape) 3, and a list too narrow for two cards keeps one per line. The columns follow the list's width as it changes (rotation, Split View).

  • Cards fill the grid left to right, then top to bottom, in row order; itemSpacing is the gap both across and down. Design the itemTemplate for a card (2 columns × 3 rows, say) rather than a full-width row.
  • Each card is the template's own grid, as tall as its rows. With the template grid's rowHeight: "auto" a card takes its content's height: the cards of one line start level, and the line is as tall as its tallest card.
  • Everything else is the list as it always is: paging asks for the same pages at the same points (a card's arrival on screen counts as its row's), keeps the same window, and searches the same way; the loading line, the row count and emptyText span the grid under the last cards. A tap sends the card's id, itemStyle: "card" draws each card's background, and an expand grows a card from where it sits.
  • VoiceOver reads the cards line by line, left to right, each one element that speaks its controls, as a templated row does.

Without an itemTemplate the setting does nothing: column rows stay one per line. Any value other than "grid" lays the rows out one per line.

Editor notes

Edit row (on the list's pose) edits itemTemplate as one row: its first row is the template, a group you move, resize, add to and take controls out of, with the group's own chips (title, columns, rows, background, theme); every row below follows at once, each filled from its own item. A stepper cycles sample items from the hub page the list is on, else its synced or starting rows, else placeholders named after the template's fields. Each control shows the {{item.<field>}} it reads above it. On a list drawn as columns the first edit creates a template from its columns. Holding Edit row offers Row layout (itemLayout: rows or a card grid); the row pose still draws the rows below the edited one a line each. hideBackground, hideLabel and tint (header color) change only the card and header, so with hideLabel on, the Header color field changes nothing on screen.

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