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
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
Field
Type
Default
What it does
Date formatformatValue
text
—
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.
Titlelabel
text
—
The heading above the rows
Shows this text as the header line above the rows in the header text size.
ColumnslistColumns
list
—
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 messageemptyText
text
—
What to show when there are no rows
Replaces the line shown when there are no rows, e.g. No books yet.
Header colortint
color
#FFFFFF
The color of the heading
Paints the header label in this color.
Hide the titlehideLabel
on / off
false(off)
Hide the heading line
Removes the header label so the rows start at the top of the card.
No background cardhideBackground
on / off
false(off)
Remove the card behind the rows
Drops the frosted card fill so the rows sit directly on the screen background.
Starting rowsdefaultValue
object[]
—
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 scrollpaging
object
—
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.pageSize
number5–200step 5
50
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.request
object
—
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.replyType
text
—
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.replyPath
text
—
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.window
number20–5000step 50
600
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.queryFrom
text
—
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 designitemTemplate
object
—
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 gapitemSpacing
number0–64step 1
2
How far apart the rows sit
Opens up space between rows, so card-style rows stand apart from each other.
Row lookitemStyle
choiceone of 2
plain
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.
plaindefaultrows sit inside the list's own card, as before
cardeach templated row is its own card, styled by the template group
Row layoutitemLayout
choiceone of 2
rows
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.
rowsdefaultone 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
Field
Type
Default
What it does
Card paddingtheme.cardPadding
number0–32step 1
12
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
Sends
When
Type
What it sends
When you tap a rowrow
tap
id
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
Takes
From
Type
What it does
rowsshow
hub, mqtt, http, store
json
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.
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.
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.
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.
The server broadcasts {"msg_type": "device_list", "devices": [{"name": "…", "status": "…", "latency": 12}, …]}; valuePath picks the row array out of the frame.
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.
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.
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.
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.
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.
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.
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:
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.