Control Center, the Lock Screen corners and the Action button. Declare them in glance.controls[]. A layout that declares none still gets controls derived from its own buttons, toggles, sliders and steppers, but those are only offered in the pick-list; a control you declare is also allowed on the Live Activity row and in medium and large widgets. See Glance Surfaces for the whole block and Glance Widgets for the interactive tiles that press the same actions.
Symbol
switch.2
Docs
Docs complete
Fields
16 fields, each with what it does.
Fields
Field
Type
Default
What it does
idid
text
—
A short name for this control
Names the control so the layout can tell it from the others; it is not shown on screen.
labellabel
text
—
The name people see
Sets the name shown on the control in the controls gallery and on the control itself.
iconicon
text
—
The little picture on the control
Sets the SF Symbol drawn on the control; when left out, each kind uses its own default.
kindkind
choiceone of 5
button
What the control does when pressed
Chooses how the control behaves in Control Center, from a plain button to a switch or a value-sending press.
togglean on/off switch, styled by on and off, that sends the opposite state
buttondefaulta plain press that sends the bound control's action or the event
cyclea press that moves to the next entry of states
stepa press that adds delta to the control's value, within its min and max
seta press that sends one fixed value
controlcontrol
text
—
Which on-screen control this one runs
Links to a control in your layout; the control shows that control's live value and a press sends its action.
eventevent
text
—
A custom message to send
Sends this named event on press instead of the linked control's action.
payloadpayload
object
—
Extra data sent with the event
Adds fixed data to the event sent on press; controls that carry a value add it alongside.
onon
object
—
How the switch looks when on
Styles a toggle in its on state with a label, icon and tint.
offoff
object
—
How the switch looks when off
Styles a toggle in its off state with a label, icon and tint.
valueControlvalueControl
text
—
Show another control's reading
Shows the formatted value of the named control as the value label, for example a sensor reading next to a toggle.
valueLabelvalueLabel
text
—
Words around the shown value
Formats the value label from a template, where {{value}} becomes the displayed reading, such as 23 lx.
statesstates
object[]
—
The choices a cycle walks through
Lists the steps a cycle control goes through in press order; each press sends the next one and the control shows the current one.
deltadelta
number
—
How much each press changes the value
Adds this amount to the control's current value on press (negative subtracts), never going past its min or max.
valuevalue
text
—
The value a press sends
Sends this exact value to the linked control when a set control is pressed.
presetspresets
string[]
—
Quick values to pick from
Lists fixed values for a step or set control, shown as one button each in buttons mode.
surfacesurface
choiceone of 3
—
How the control shows up outside the app
Chooses whether the control appears as a row of buttons, one cycling button, or a tap that opens a full-screen sheet.
buttonsa row of press buttons, one per option
cycleone button that walks through the options
biga tap that opens the app on a full-screen sheet for this one control
Examples
3 examples, each one a control you can paste into a layout.
Controls are the glance block's buttons and switches that work outside the app:
What iOS allows
Apple gives Control Center exactly two templates: a toggle and a button. There is no
slider and no text field. The kinds map like this:
Kind
Shows
A press sends
toggle
on or off, styled by on / off, with an optional value label
the opposite state, {"value": <bool>} merged into payload
button (default)
a label and icon
the bound control's action, or event / payload
cycle
the current entry of states
the next entry's value
step
the bound control's value
its value plus delta, clamped to the control's min/max
set
a label
value
A slider therefore becomes step buttons (or presets), and a multi-state picker a
cycle. The user places every control by hand; the app can only offer them.
Value display
A control can show a reading, not just a name. A toggle shows the bound control's
formatted value; to show another control's reading, name it in valueControl, and
shape it with valueLabel: "valueLabel": "{{value}} lx".
Delivery
Presses work with the app closed: the control posts straight to the relay
(POST /mesh/broadcast) with the layout's own credential, exactly the frame the
in-app control would send. Offline presses queue for 24 hours. The rendered state
flips only once the relay confirms the frame was published; a press that reached
nothing is rolled back and reported. live.controls.refresh (push on iOS 18, or
app) sets how the displayed value is refreshed; see Live Activity and Dynamic Island.
Constraints
The frontmatter constraints block gives, per kind: the iOS template used, whether a
bound control is required, which other fields it needs, and whether it shows a
value. It also lists the surface modes and the 24 h press queue.
Generated from ControlDocs/control-center.md. Something unclear or missing? Tell me.