A widget is a scene (rows of tiles) the user places on the Home Screen, Lock Screen, StandBy or CarPlay through the CAR-TER Scene widget. Declare them in glance.widgets[]. This page is the reference for the widget block; the tile vocabulary lives in Glance Surfaces, the other surfaces in Live Activity and Dynamic Island, Lock Screen and Control Center Controls.
Symbol
rectangle.grid.2x2
Docs
Docs complete
Fields
8 fields, each with what it does.
Fields
Field
Type
Default
What it does
idid
text
—
The widget's name tag
Names this widget so the Home Screen gallery can offer it as the title plus the layout name.
titletitle
text
—
The name shown in the widget gallery
Sets the name people see when picking the widget; the id is used when it is left out.
iconicon
text
—
The small picture in the gallery
Shows this SF Symbol next to the widget in the gallery.
familiesfamilies
string[]
—
Which widget sizes to offer
Limits the sizes people can add, such as small, medium or lock screen; leave it out to offer every size.
scenescene
object
—
What the widget shows
Defines the rows of tiles every listed size draws, re-flowed to fit each size unless that size has its own entry.
columnscolumns
number1–12step 1
—
How many columns the tiles share
Sets the columns the scene lays out against, 1 to 12; it defaults to the widest row.
rowsrows
object[]
—
The lines of tiles
Lists the rows of tiles, each row an array of tiles such as a gauge, value or toggle.
systemSmallsystemSmall
object
—
A different version for one size
Replaces the scene for that size only, so a small widget can show one gauge while a medium one shows more.
Examples
3 examples, each one a control you can paste into a layout.
A layout that declares no widgets still offers the zero-config Layout Glance
(hero + slots) and Control Value (any single control) widgets.
How a scene fits each family
One scene serves every family; the app re-flows it to what the family can show.
An entry under the family's own name always wins over the re-flow.
Family
What renders from the base scene
Interactive tiles
systemSmall
the first row only
yes
systemMediumsystemLargesystemExtraLarge
the scene as authored (columns capped at 12)
yes
accessoryRectangular
the first row, non-interactive tiles drawn as values, monochrome
no
accessoryCircular
one tile: the first gauge or ring, else the first bound value, else the first bound tile
no
accessoryInline
one tile as "label value": the first bound tile
no
So design for the smallest family you list: put the tiles that matter most in the
first row, and add per-family overrides where the re-flow is not what you want.
A widget lists its families; leave families out to offer every one.
Constraints
The constraints block in this page's frontmatter carries the same limits as JSON
for tools: per family the maxRows, maxTiles (where the family takes one), the
reflow rule and the allowedTiles. maxRows: null means the code sets no limit
(iOS does: widgets do not scroll, so keep to what fits). Rules enforced when a layout loads
(SurfaceSceneValidator, shown in the connection console):
A row wider than the scene's columns is clipped; a tile may not span more columns than the scene has.
A tile that needs a number (gaugeringbarsparklinetimerstep) must bind a numeric control.
toggle binds a toggle control; step binds a slider or stepper.
A pressed tile needs an action to send, and from a widget only MeshSocket and open actions can fire.
An unknown control id drops that tile and nothing else; an unknown tile kind renders as value.
Generated from ControlDocs/widgets.md. Something unclear or missing? Tell me.