Guide / Controls / Reference

Control Center Controls

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
FieldTypeDefaultWhat it does
ididtext—

A short name for this control

Names the control so the layout can tell it from the others; it is not shown on screen.

labellabeltext—

The name people see

Sets the name shown on the control in the controls gallery and on the control itself.

iconicontext—

The little picture on the control

Sets the SF Symbol drawn on the control; when left out, each kind uses its own default.

kindkindchoiceone of 5button

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
  • button defaulta 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
controlcontroltext—

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.

eventeventtext—

A custom message to send

Sends this named event on press instead of the linked control's action.

payloadpayloadobject—

Extra data sent with the event

Adds fixed data to the event sent on press; controls that carry a value add it alongside.

ononobject—

How the switch looks when on

Styles a toggle in its on state with a label, icon and tint.

offoffobject—

How the switch looks when off

Styles a toggle in its off state with a label, icon and tint.

valueControlvalueControltext—

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.

valueLabelvalueLabeltext—

Words around the shown value

Formats the value label from a template, where {{value}} becomes the displayed reading, such as 23 lx.

statesstatesobject[]—

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.

deltadeltanumber—

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.

valuevaluetext—

The value a press sends

Sends this exact value to the linked control when a set control is pressed.

presetspresetsstring[]—

Quick values to pick from

Lists fixed values for a step or set control, shown as one button each in buttons mode.

surfacesurfacechoiceone 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.

Lights toggle with a lux reading

A toggle styled per state, showing the lux sensor beside it.

JSON 8 lines
{
  "controls": [
    { "id": "lights", "kind": "toggle", "label": "Lights", "control": "lights-toggle",
      "valueControl": "nozzle", "valueLabel": "{{value}} °C",
      "on":  { "label": "Lit",  "icon": "lightbulb.fill", "tint": "#FFD60A" },
      "off": { "label": "Dark", "icon": "lightbulb" } }
  ]
}

Fan: cycle and step

A three-state cycle, and a step button that adds 10 to the fan speed slider.

JSON 10 lines
{
  "controls": [
    { "id": "fan", "kind": "cycle", "label": "Fan", "control": "fan-mode",
      "states": [ { "value": "off",  "label": "Off",  "icon": "fan" },
                  { "value": "low",  "label": "Low",  "icon": "fan", "tint": "#64D2FF" },
                  { "value": "high", "label": "High", "icon": "fan.fill", "tint": "#0A84FF" } ] },
    { "id": "fan-up", "kind": "step", "label": "Fan +10", "control": "fan-speed", "delta": 10,
      "surface": "buttons", "presets": [25, 50, 75, 100] }
  ]
}

Pause button and preset

A plain button with an explicit event, and a set that sends one value.

JSON 7 lines
{
  "controls": [
    { "id": "pause", "kind": "button", "label": "Pause", "icon": "pause.fill",
      "event": "printer.pause", "payload": { "reason": "control-center" } },
    { "id": "fan-max", "kind": "set", "label": "Fan max", "control": "fan-speed", "value": 100 }
  ]
}

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.