Guide / Controls / Reference

Lock Screen

Three things live on the Lock Screen, and they are configured in three places:

Symbol
lock.iphone
Docs
Docs complete

Fields

3 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
lockScreenlockScreenobject—

What the Lock Screen banner shows

Sets the tiles drawn in the banner of a running Live Activity; left out, it repeats the island's bottom area.

columnscolumnsnumber1–12step 1—

How many columns wide

Sets the columns the banner lays out against, up to 12; left out, it uses the widest row.

rowsrowsobject[]—

The rows of tiles

Lists the banner's rows from top to bottom, each row an array of tiles.

Examples

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

Banner with two rows

A status row and a control row, with the controls declared so the buttons show.

JSON 13 lines
{
  "liveActivity": true,
  "controls": [
    { "id": "pause", "kind": "button", "label": "Pause", "control": "pause" },
    { "id": "lights", "kind": "toggle", "label": "Lights", "control": "lights-toggle" }
  ],
  "lockScreen": {
    "rows": [
      [ { "tile": "gauge", "control": "nozzle" }, { "tile": "ring", "control": "progress" }, { "tile": "timer", "control": "eta" } ],
      [ { "tile": "button", "control": "pause" }, { "tile": "toggle", "control": "lights-toggle" } ]
    ]
  }
}

Banner as a single tile

A bare tile is accepted where a scene is expected and becomes one row.

JSON 4 lines
{
  "liveActivity": true,
  "lockScreen": { "tile": "bar", "control": "progress" }
}

Circular accessory with a status row

A circular lock-screen widget that shows the print progress ring, beside a rectangular one.

JSON 7 lines
{
  "widgets": [
    { "id": "lock", "title": "Print progress",
      "families": ["accessoryCircular", "accessoryRectangular"],
      "scene": { "rows": [ [ { "tile": "ring", "control": "progress" }, { "tile": "value", "control": "nozzle" } ] ] } }
  ]
}
What Declared in Notes
The banner of a running Live Activity lockScreen (this page) a scene; defaults to expanded.bottom of the island
Accessory widgets (circular, rectangular, inline) widgets[] with those families, see Glance Widgets monochrome, not interactive
Corner controls controls[], see Control Center Controls toggle and button only to iOS; the user places them

The banner needs a running Live Activity, so it follows the rules in Live Activity and Dynamic Island: "liveActivity": true (or live.activity.start), 4 KB of state per update, 8 hours per session. Its scene is drawn with the same tiles as everywhere else (Glance Surfaces), in the app's Glass look.

The banner is wider and taller than the island's bottom region, so a scene of two or three rows fits. Interactive tiles (toggle, button, step) show only for controls the author declared in glance.controls[], so declare the ones you want to press from the banner; auto-derived controls stay pick-list-only.

If you leave lockScreen out, the banner repeats island.expanded.bottom. Write it when the banner should show more than the island can.

Accessory widgets

Accessory families are small and drawn in the system's monochrome, so a gauge arc reads as a smudge where a number reads as a number. The re-flow rules, applied when you give no override:

  • accessoryRectangular: the first row, non-interactive tiles drawn as values.
  • accessoryCircular: the first gauge or ring, else the first bound value.
  • accessoryInline: "label value" of the first bound tile.

Give an override ("accessoryCircular": { "rows": <span class="wikibroken" title="unresolved: …">…</span> } inside the widget) to choose the tile yourself.

Constraints

The frontmatter constraints block lists, as JSON, the banner's limits, the three accessory families with their tile limits and allowed tiles, and the corner-control kinds. Interactive tiles are not offered on accessories: iOS shows no controls in those slots.

Generated from ControlDocs/lock-screen.md. Something unclear or missing? Tell me.