Guide / Controls / Reference

Group

A visual container that clusters controls into a glass card with its own internal grid.

Also titled
Group Definition
Default size
3 rows × 2 columns
Symbol
square.grid.3x3.square
Docs
Docs complete
Search for it as
  • box
  • card
  • container
  • cluster
  • frame
  • live
  • dynamic
  • slot

Fields

28 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
Typetypechoiceone of 1—

Always group

Marks this entry as a group card rather than a control.

  • groupthe only value; a container card with its own grid
IDidtext—

Its unique name

Lets bindings, visibility and expand triggers point at this group; no two things in a layout share one.

Namenametext—

A friendly name for the editor

Labels the group in the editor lists; nothing on the page shows it.

Headerlabeltext—

The title at the top of the card

Shows this text as a header above the group; leave it out for no header.

Positionpositionlist—

Which cell it starts in

Puts the group's top-left corner at this row and column of the page.

Sizespanlist—

How many cells it covers

Makes the group this many rows and columns big on the page; default one cell.

Landscape placelandscapeobject—

Its place when the phone is on its side

Moves or hides the group when an iPhone is turned sideways.

Tablet placeregularobject—

Its place on an iPad

Moves or hides the group on an iPad-width page.

Inner gridgridobject—

The cells inside the card

Sets the columns, rows, row height and scale the group's controls are laid out on.

Columnsgrid.columnsnumber1–12step 1—

How many columns the group's controls share

Splits the group's card into this many equal columns (1 to 12); its controls sit on them.

Spacinggrid.spacingnumber0–32 ptstep 18

How far apart the group's controls sit

Sets the gap between the controls in the group's card, 0 to 32 points; 0 butts them together, and Default goes back to the theme's 8.

Rowsgrid.rowsnumber1–50step 1—

How many rows the group's card holds

Gives the group's card this many rows of cells (1 to 50); more rows fit more controls.

Row heightgrid.rowHeightnumber12–200 ptstep 156

How tall each row of the group is

Makes every row of the group's card this many points tall (12 to 200); Default goes back to 56.

Scalegrid.scalenumber0.3–1.5step 0.051

How big the group's controls are drawn

Draws every control in the group smaller or bigger, text, padding, corners and icons together, so a fine grid holds whole controls; taps still get a full-size target. Auto shrinks them by the group's shape: a group 1 row by 5 columns holding a 3 by 15 grid draws them at a third. Default goes back to 1.

Contentschildrenobject[]—

What is inside the group

Lists the controls and smaller groups drawn in the card.

Live eventdynamictext—

Contents that arrive live

Replaces the children whenever a broadcast with this event name arrives.

Show whenvisibleobject—

Show only when...

Hides the whole group unless another control's value meets the condition.

Enabled whenenabledobject—

Allow touches only when...

Dims the group and ignores touches on all its controls while the condition is false.

Formformobject—

Turn the card into a form

Makes the inputs inside write to a draft that is saved once when submitted.

Background on/offhideBackgroundon / offfalse (off)

Drop the glass card

Removes the card background so the controls sit directly on the page.

Pulsepulseobject—

Flash when something arrives

Flashes a ring around the group each time the chosen live event lands.

Themethemeobject—

Colours and style for the card

Overrides the header, card and every child's theme; a child's own theme still wins.

Expandexpandobject—

Let the group open up full screen

Tapping the card (a tap no child claims), holding it, or both: the group's card grows from where it sits into the whole screen (or a large sheet), its controls laid out bigger with more of them, and shrinks back when closed.

Opens byexpand.triggertextone of 4tap

How the group opens

Opens the group on a tap, a hold, either, or never from the card (none); or when a control you pick on the page is tapped. A keyword and controls can combine.

  • tap default
  • hold
  • both
  • none
Styleexpand.styletextone of 2fullScreen

Full screen or a sheet

Full screen takes the whole display; a sheet rises as a large card over the dimmed page. Both close with the corner X or a drag down.

  • fullScreen default
  • sheet
Titleexpand.titletext—

The expanded page's heading

Types the heading the expanded group shows at its top; leave it empty to use the group's own title.

Actionactionobject—

Make the whole card tappable

Taps on the card's non-interactive parts send the action; buttons, toggles, sliders, inputs and rows with their own action keep their own taps. The card dips slightly while pressed.

Extensionsextensionsobject—

Notes for other tools

Stores tool data under reverse-DNS names that the app keeps but never uses.

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 the cardtaptapstring

only what the action itself carries; the group adds no value

Fires only for a tap no child claims, and not when the group expands on tap

Example: true

Examples

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

Bedroom card

A titled card with two switches and a brightness slider on a two-column grid.

JSON 13 lines
{
  "type": "group",
  "id": "bedroom",
  "label": "Bedroom",
  "position": [2, 0],
  "span": [2, 2],
  "grid": { "columns": 2, "rows": 2 },
  "children": [
    { "type": "toggle", "id": "br-light", "position": [0, 0], "label": "Light" },
    { "type": "toggle", "id": "br-fan", "position": [0, 1], "label": "Fan" },
    { "type": "slider", "id": "br-dim", "position": [1, 0], "span": [1, 2], "min": 0, "max": 100, "label": "Brightness" }
  ]
}

Open in CAR-TER

Hold to expand

A card that opens as a large sheet when held, with the same toggle placed larger inside.

JSON 19 lines
{
  "type": "group",
  "id": "lamp",
  "label": "Lamp",
  "position": [0, 0],
  "span": [1, 2],
  "grid": { "columns": 2, "rows": 1 },
  "expand": {
    "trigger": "hold",
    "style": "sheet",
    "grid": { "columns": 2, "rows": 3 },
    "children": [
      { "ref": "lamp-power", "position": [0, 0], "span": [1, 2] }
    ]
  },
  "children": [
    { "type": "toggle", "id": "lamp-power", "position": [0, 0], "span": [1, 2], "label": "Power" }
  ]
}

Open in CAR-TER

Quiet background-free group

A group with no glass card and a pulse ring that flashes when a live event lands.

JSON 12 lines
{
  "type": "group",
  "id": "status",
  "position": [1, 0],
  "span": [1, 2],
  "hideBackground": true,
  "grid": { "columns": 2, "rows": 1 },
  "pulse": { "event": "broadcast", "direction": "inward", "color": "34C759" },
  "children": [
    { "type": "label", "id": "status-text", "position": [0, 0], "span": [1, 2], "text": "Waiting for data" }
  ]
}

Open in CAR-TER

Editing a group

The editor's + lists Group and Live group under Layout, from this doc's starterPreset and starterVariants: a Group lands as an empty card with a 2 × 2 inner grid, a Live group is the same card with dynamic set (a slot a server fills). Either lands where the + was opened (the page, the page of a container you are inside, or a group's Expanded layout), selected with its Group pane up.

Tapping a group in the editor opens its Group pane. It edits the group's scalar fields above (name, header, background), its inner grid (the Grid Dimensions fields: columns with spacing under a hold on Columns, rows with row height and scale under a hold on Rows, arrangement, landscape policy), and three keys of its theme that shape the card: accentColor (Tint), cardPadding (Padding) and cornerRadius (Corners). Edit controls opens the group so its children can be tapped and edited; Ungroup moves the children up into the parent where they sat; Delete removes the group and everything in it (undo brings it back).

A container's page (a carousel page, an accordion section, a flip-card face) is a group too: inside it, tapping its open page chip opens the Page pane with the same chips (header, Columns with Spacing, Rows, Background and the card's theme, Padding among them), written into that page of the container's panels. A page does not expand, so it has no Expanded pose.

Collapsed | Expanded (the expand field's edit: pose) flips the pane to the group's expanded layout: the grown card's grid (expand.grid), with each child the expand does not place yet as a ghost at its collapsed cell. Dragging a child into cells writes its {ref, position, span} entry in expand.children (the first one creates expand: trigger: "tap", style: "fullScreen", the group's columns on a taller grid); the corner handle resizes it (its span); dragging it off the card removes the ref, and once the expand places any child the unplaced ones fade while expanded (the pose then shows them on a faded shelf below the card, to drag in from there). Columns and Rows on the bar size expand.grid; Don't expand removes expand. Each drag is one undo step. Controls that exist only while expanded show with an Only here mark.

Scale

grid.scale draws the group's controls as proportional miniatures (or enlargements): text, padding, spacing, corner radii, icons and control sizes (toggle tracks, slider thumbs, stepper buttons) all scale together through the theme, so they stay crisp instead of being shrunk as a picture. It is what makes a fine grid work: a group 1 row × 5 columns on its page holding a 3 × 15 grid stacks three 1 × 1 controls in that one row, each looking like a 1 × 1 outside the group at a third of the size.

Value Draws at
absent 1 (as today)
a number that factor, clamped to 0.3 to 1.5 (0.5 = half size)
"auto" the group's shape: the smaller of span rows / grid rows and span columns / grid columns, at most 1 (span 1 × 5 with a 3 × 15 grid: 1/3; span 2 × 4 with a 2 × 4 grid: 1). Each inner row is that factor times the page's row, so a 1 × 1 inside is a 1 × 1 outside at that size. A grid that sets a rowHeight number keeps rowHeight / 56 (28 pt rows: 0.5); rowHeight: "auto" draws at 1
  • Taps stay full size: a button, toggle or stepper drawn smaller than 44 pt still takes a 44-pt touch around its centre.
  • It scales what is inside the group, not the group's own header (it follows the grid the group sits in). With "auto" from the shape the inner rows fill the span exactly: the card pads only the sides (at the same factor), and each row gives up its share of the page's gap (three rows at a third can't quite fit one page row, so each is about 17 pt, not 18.7), so a control that fits a 1 × 1 outside never runs into its neighbour inside. A header takes its height from those rows. A group nested inside a scaled group is scaled with it (its rows too), times its own scale.
  • Visual controls (rings, gauges, charts) already scale their insides to their cell, so they look the same at any scale; the factor matters most for labels, buttons and inputs.
  • A list's itemTemplate grid takes scale too, so every row draws at it; with "auto" a row is one row cell, so a 3-row template draws at 1/3. An expand page draws at its own grid.scale ("auto" from the foreground container measured in page cells), and at 1 when it has no grid of its own.
  • The editor draws a group's inside at the same scale when you open it.

Three 1 × 1 controls stacked in one row of a 5-column page: a 1 × 5 group with a 3 × 15 grid draws them at auto = min(1 / 3, 5 / 15) = 1/3:

{
  "type": "group",
  "id": "mini-stack",
  "position": [0, 0],
  "span": [1, 5],
  "grid": { "columns": 15, "rows": 3, "scale": "auto" },
  "children": [
    { "type": "label", "id": "ms-name", "position": [0, 0], "span": [1, 1], "text": "Name" },
    { "type": "toggle", "id": "ms-on", "position": [1, 0], "span": [1, 1], "label": "On" },
    { "type": "button", "id": "ms-go", "position": [2, 0], "span": [1, 1], "label": "Go" }
  ]
}

Dynamic Groups

When dynamic is set, the group's children are replaced at runtime by content arriving over MeshSocket. The incoming broadcast must have msg_type matching the dynamic value and a children array.

{
  "type": "group",
  "id": "now-playing",
  "label": "Now Playing",
  "position": [0, 0],
  "span": [3, 4],
  "grid": { "columns": 4, "rows": 3 },
  "children": [],
  "dynamic": "player_state"
}

Chunked decks (rev, part, parts)

The relay drops any websocket frame over its read limit (256 KiB on Connect+, and an E2EE room seals and base64-encodes the frame, so it grows by about a third on the wire). A server whose deck may come near that size splits it into several broadcasts. Each one carries the same msg_type plus three extra keys:

Key Type Rule
rev string Identifies one deck. Every part of the deck carries the same rev; use a new rev (a counter, a timestamp, a content hash) for each new deck. At most 256 UTF-8 bytes.
parts integer Total number of parts, 2...64. A frame whose parts is missing, not a number (for example a string), or a number of 1 or less is a normal single-frame deck.
part integer This frame's index. Number parts 1...parts (1-based). CAR-TER 1.2.6 and later also accept 0-based 0...parts-1.
children array This part's slice of the deck: whole child objects. Split between children, never inside one.
{ "msg_type": "player_state", "rev": "42", "part": 1, "parts": 2, "children": [ { "type": "label", "id": "dyn-title", "position": [0, 0], "span": [1, 4], "text": "Song" } ] }
{ "msg_type": "player_state", "rev": "42", "part": 2, "parts": 2, "children": [ { "type": "slider", "id": "dyn-volume", "position": [1, 0], "span": [1, 4], "min": 0, "max": 100 } ] }

How the app puts a deck back together:

  • It buffers parts per group. Once it holds parts distinct part indices for one rev, it concatenates the children slices in ascending part order and applies the result as one deck. Parts can arrive in any order.
  • A frame with a different rev or parts than the buffered deck throws away the unfinished deck and starts a new one. Only one deck is in flight per group. The newest deck wins, and an abandoned one never renders half-built.
  • The app drops a frame, without logging it, if parts is not a whole number from 2 to 64, if part is missing or outside 0...parts, if rev is missing, not a string or longer than 256 bytes, or if children is not an array.
  • Use one numbering convention for the whole deck. If a sender mixes them (say, 0, 1 and 2 with parts: 2), the deck completes as soon as it has two distinct indices, so it can apply only part of the deck.
  • The app rebuilds the deck as msg_type set to the group id, plus the joined children. Other top-level keys on the parts are ignored.
  • Use 1-based numbering. Before 1.2.6, the app reassembled 1...parts only: 1.2.5 drops part 0, so a 0-based deck never completes on it. Send 0-based parts only to 1.2.6 and later.
  • Chunking applies to dynamic groups only. A dynamic tab always arrives as one frame.

A carterkit helper builds these frames for you once a release ships it: carterkit.dynamic.chunk_deck(event, children) returns the frame list (1-based), and Hub.fill(group, children, max_bytes=...) sends a deck in parts when it is larger than max_bytes. Check the installed carterkit for chunk_deck before relying on it; otherwise split the deck by hand.

Pulse

Set pulse to make the group flash a ring whenever a server event arrives — a lightweight way to visualise live data landing in a group without wiring a control. The ring expands outward (e.g. data collected/leaving) or contracts inward (e.g. data arriving/stored), then fades. An optional filter narrows which payloads trigger it, matching keys the same way a Sync filter does.

Field Type Description
event string Server event that fires the pulse
color hex string Ring colour (default: green 34C759)
direction "outward" | "inward" Pulse direction (default: outward)
filter object Optional payload match, e.g. { "device": "thunk-app" }
{
  "type": "group",
  "id": "gps-collector",
  "label": "Live GPS",
  "position": [0, 0],
  "grid": { "columns": 2, "rows": 2 },
  "children": [],
  "pulse": { "event": "broadcast", "filter": { "msg_type": "iCloudListen" }, "direction": "outward", "color": "34C759" }
}

Theming

A group renders as a glass card whose surface, corner radius, border, and padding come from the active theme (surfacePrimary, cornerRadius, borderColor, borderWidth, cardPadding). Set hideBackground: true for a transparent group (no card), e.g. a hero row of status lights. A group's own theme overrides those keys for the card, its label and everything inside it, e.g. "theme": {"accentColor": "$leaf", "surfacePrimary": "#1B2A1F"}; per-control theme overrides on the children still apply on top. See Cascade.

Expand

expand lets a person open a group up: tapping the card (a tap no child claims), or holding it, grows the card from where it sits, in one continuous motion, into a foreground container with a close (X) in its corner. As it grows, the group's own controls move from their cells to new ones on the expand grid: the same controls, not copies, so their live values, bindings and actions carry straight through. Controls that only make sense with room fade and scale in once it has grown. The X, a drag down on the container's top edge, or a tap on the dimmed page (sheet style) plays it backwards to where the group sits.

Key Type Default Description
trigger "tap", "hold", "both", "none", a control id, or an array mixing them "tap" What opens it. tap: a tap on the card; hold: a hold on the card; both: either; none: only buttons, actions or the hub. A control id (a child of the group or any control in the layout; inside a list's itemTemplate the id resolves in the same row) expands the group when that control is tapped, and the control's own action still fires. Examples: "hold", "more", ["hold", "more"]. A child's own tap or hold always wins over the card's; only a tap on non-interactive content, the background or the padding opens it. An id that matches no control never fires. An old "icon" reads as "tap". Edits take effect live
style "fullScreen" or "sheet" "fullScreen" The whole screen, or a large card up from the bottom over the dimmed page
grid Grid Dimensions the group's grid The grid the expanded layout is placed on
children object[] — Placements and expanded-only controls, below
title string the group's label Text beside the close button

Each entry of children is one of two things:

  • A placement of one of the group's children: {"ref": "<child id>", "position": [row, col], "span": [rows, cols]}. Other fields in it are laid over that child while expanded (a bigger size, another style); id and type are ignored. A ref that names no child of this group is skipped.
  • A control or group of its own (it needs a type; the id may be left out). It exists only while expanded.

A child that no entry refers to fades out while expanded and comes back on collapse. An expand with no children keeps every child where it is, on the expand grid. While a group expands its controls are laid out on grid cells (the expand grid's rows), even when the group's own grid is a flow grid.

A one-row card (an image, a label with two lines of text, two buttons) that opens into a page: the image large at the top left, the text beside it, the buttons below, and a description only the page has.

{ "type": "group", "id": "pkg", "position": [0, 0], "span": [2, 4],
  "grid": { "columns": 4, "rows": 2 },
  "expand": {
    "trigger": ["tap", "more"], "style": "fullScreen", "title": "Example package",
    "grid": { "columns": 4, "rows": 6 },
    "children": [
      { "ref": "icon", "position": [0, 0], "span": [2, 2] },
      { "ref": "name", "position": [0, 2], "span": [2, 2] },
      { "ref": "install", "position": [2, 0], "span": [1, 2] },
      { "ref": "share", "position": [2, 2], "span": [1, 2] },
      { "type": "label", "id": "about", "position": [3, 0], "span": [3, 4],
        "text": "A longer description that only the expanded page shows." }
    ]
  },
  "children": [
    { "type": "image", "id": "icon", "position": [0, 0], "systemName": "shippingbox" },
    { "type": "label", "id": "name", "position": [0, 1], "label": "Version 1.2.0", "text": "Example package" },
    { "type": "button", "id": "more", "position": [1, 0], "span": [1, 4], "label": "More" },
    { "type": "button", "id": "install", "position": [0, 2], "label": "Install",
      "action": { "method": "meshsocket", "event": "install", "payload": { "id": "pkg" } } },
    { "type": "button", "id": "share", "position": [0, 3], "label": "Share",
      "action": { "method": "meshsocket", "event": "share", "payload": { "id": "pkg" } } }
  ] }

A Card padding's itemTemplate is a group too: give it an expand and every row grows the same way. Its refs are the template's child ids (each row's own controls move), and its placements and new controls are filled in from the row ({{item.<field>}}). Nothing inside an expanded group offers to expand again, except a templated row of a list in it, which opens on top with a back button.

Hub sheets

The hub of the layout on screen can expand a group itself, with the routed sheet verb on the layout's own socket: {id, groupId} expands that group of the layout (live, from where it sits when it is on screen); {id, group} opens a group definition of the hub's own, drawn from its fields like a list's item template and replaced in place when a frame with the same id arrives again. title and style are optional and {id, close: true} closes it. A hub's own group sends only to the hub: actions of any other method are dropped, as are sync and form, and {{secret:…}} never resolves in it. When it closes the app broadcasts sheet_closed {id, reason}. Wire contract: docs/HUB-SHEET.md in the app repository.

Rendering

  • Groups render as a glass card (frosted material + subtle border)
  • The internal grid is independent of the parent grid
  • Groups can be nested (a group's children can include other groups)

Generated from ControlDocs/group-def.md. Something unclear or missing? Tell me.