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
Field
Type
Default
What it does
Typetype
choiceone 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
IDid
text
—
Its unique name
Lets bindings, visibility and expand triggers point at this group; no two things in a layout share one.
Namename
text
—
A friendly name for the editor
Labels the group in the editor lists; nothing on the page shows it.
Headerlabel
text
—
The title at the top of the card
Shows this text as a header above the group; leave it out for no header.
Positionposition
list
—
Which cell it starts in
Puts the group's top-left corner at this row and column of the page.
Sizespan
list
—
How many cells it covers
Makes the group this many rows and columns big on the page; default one cell.
Landscape placelandscape
object
—
Its place when the phone is on its side
Moves or hides the group when an iPhone is turned sideways.
Tablet placeregular
object
—
Its place on an iPad
Moves or hides the group on an iPad-width page.
Inner gridgrid
object
—
The cells inside the card
Sets the columns, rows, row height and scale the group's controls are laid out on.
Columnsgrid.columns
number1–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.spacing
number0–32 ptstep 1
8
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.rows
number1–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.rowHeight
number12–200 ptstep 1
56
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.scale
number0.3–1.5step 0.05
1
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.
Contentschildren
object[]
—
What is inside the group
Lists the controls and smaller groups drawn in the card.
Live eventdynamic
text
—
Contents that arrive live
Replaces the children whenever a broadcast with this event name arrives.
Show whenvisible
object
—
Show only when...
Hides the whole group unless another control's value meets the condition.
Enabled whenenabled
object
—
Allow touches only when...
Dims the group and ignores touches on all its controls while the condition is false.
Formform
object
—
Turn the card into a form
Makes the inputs inside write to a draft that is saved once when submitted.
Background on/offhideBackground
on / off
false(off)
Drop the glass card
Removes the card background so the controls sit directly on the page.
Pulsepulse
object
—
Flash when something arrives
Flashes a ring around the group each time the chosen live event lands.
Themetheme
object
—
Colours and style for the card
Overrides the header, card and every child's theme; a child's own theme still wins.
Expandexpand
object
—
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.trigger
textone of 4
tap
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.
tapdefault
hold
both
none
Styleexpand.style
textone of 2
fullScreen
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.
fullScreendefault
sheet
Titleexpand.title
text
—
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.
Actionaction
object
—
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.
Extensionsextensions
object
—
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
Sends
When
Type
What it sends
When you tap the cardtap
tap
string
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.
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:
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.
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.
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" }
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
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.
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)