Guide / Controls / Reference

Live Activity and Dynamic Island

The Live Activity is the glance block's most visible surface: the Dynamic Island (compact, minimal and expanded) and, on the Lock Screen, a banner. This page covers the island and the liveness settings; the banner is Lock Screen. Tiles are defined in Glance Surfaces.

Symbol
platter.filled.top.and.arrow.up.iphone
Docs
Docs complete

Fields

17 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
liveActivityliveActivityon / off—

Turn on the Dynamic Island

Starts a Live Activity in the Dynamic Island and Lock Screen while the layout is connected; off by default.

compactLeadingcompactLeadingobject—

Left side of the small island

Fills the left of the compact island with one tile; without it the layout icon shows and bounces on update.

compactTrailingcompactTrailingobject—

Right side of the small island

Fills the right of the compact island with one tile; without it the main value, ring or dot shows.

minimalminimalobject—

Tiny island view

Fills the minimal island, used when another app's activity shares the island, with one tile; without it a freshness ring circles the connection dot.

expandedexpandedobject—

The big island when you press it

Fills the leading, trailing, center and bottom areas of the expanded island, each with a tile or a scene.

keylinekeylinetext—

Island outline color

Colors the outline around the island; iOS only draws it on a full-black background. Use accent, a hex color or none.

live.tierlive.tierchoiceone of 4fresh

How live everything feels

Sets a preset for how often the island, widgets and Control Center controls update; fields set explicitly override it.

  • realtimeupdates every second or two and pushes widgets as things change, using up budgets quickly
  • fresh defaultlive while the app is open and updated every few seconds from the relay, safe to leave on all day
  • periodicupdates slowly with a pull every 15 minutes, almost free
  • manualonly updates when the app itself pushes a change
live.activity.cadencelive.activity.cadencenumber1–3600step 1—

Update speed while the app is open

Sets how many seconds pass between island updates while the app is open, from 1 to 3600.

live.activity.remoteCadencelive.activity.remoteCadencenumber2–3600step 1—

Update speed from the relay

Sets how many seconds pass between island updates pushed by the relay when the app is closed, from 2 to 3600.

live.activity.stalelive.activity.stalenumber30–3600step 1—

When the data counts as old

Sets how many seconds until the island marks its data stale, ending the LIVE clock and greying the freshness dot (default 120, minimum 30).

live.activity.prioritylive.activity.prioritychoiceone of 2—

How urgently updates are pushed

Chooses whether relay pushes ask iOS to deliver immediately or when convenient.

  • immediatedelivered right away but counted against an iOS budget
  • opportunisticdelivered when iOS finds it convenient, which can lag
live.activity.startlive.activity.startchoiceone of 3onConnect

When the island starts

Chooses what starts the Live Activity.

  • onConnect defaultit starts when the layout connects
  • remoteonly a hub can start it, by push-to-start
  • neverit stays off
live.widgets.refreshlive.widgets.refreshchoiceone of 3—

How widgets update

Chooses how home screen widgets get fresh data.

  • pushthe relay pushes widgets when data changes
  • pullwidgets fetch new data on a timer
  • appwidgets only change when the app updates them
live.widgets.pullEverylive.widgets.pullEverynumber300–86400step 60—

How often widgets fetch

Sets seconds between widget fetches in pull mode, from 300 to 86400.

live.widgets.stalelive.widgets.stalenumber30–86400step 1—

When widget data counts as old

Sets how many seconds until a widget calls its data stale, from 30 to 86400.

live.controls.refreshlive.controls.refreshchoiceone of 2—

How Control Center buttons update

Chooses how Control Center controls get fresh data.

  • pushthe relay pushes updates when data changes
  • appcontrols only change when the app updates them
live.background.silentPushlive.background.silentPushon / off—

Also wake the app quietly

When on, relay updates also send a silent push that wakes the app in the background; iOS throttles it heavily.

Examples

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

Printer island

Compact ring and light, expanded gauges with a timer in the centre.

JSON 18 lines
{
  "title": "Printer", "icon": "printer.fill", "tint": "#FF9F0A",
  "hero": "nozzle", "slots": ["bed", "progress"],
  "liveActivity": true,
  "live": { "tier": "fresh" },
  "island": {
    "compactLeading":  { "tile": "icon", "effect": "bounce" },
    "compactTrailing": { "tile": "ring", "control": "progress" },
    "minimal":         { "tile": "light", "control": "state" },
    "expanded": {
      "leading":  { "tile": "icon" },
      "trailing": { "tile": "freshness" },
      "center":   { "tile": "timer", "control": "eta" },
      "bottom":   { "rows": [ [ { "tile": "gauge", "control": "nozzle" }, { "tile": "gauge", "control": "bed" } ],
                              [ { "tile": "button", "control": "pause" }, { "tile": "step", "control": "fan-speed", "delta": 10 } ] ] }
    }
  }
}

Quiet island

Only the compact trailing value and a keyline; every other region keeps its default.

JSON 9 lines
{
  "liveActivity": true,
  "hero": "nozzle",
  "live": { "tier": "periodic", "activity": { "stale": 300 } },
  "island": {
    "compactTrailing": { "tile": "value", "control": "nozzle" },
    "keyline": "none"
  }
}

Remote-started session

A hub starts the activity by push-to-start; cadence is set explicitly.

JSON 12 lines
{
  "liveActivity": true,
  "live": {
    "tier": "realtime",
    "activity": { "cadence": 1, "remoteCadence": 2, "stale": 60, "priority": "immediate", "start": "remote" },
    "background": { "silentPush": false }
  },
  "island": {
    "minimal": { "tile": "ring", "control": "progress" },
    "expanded": { "center": { "tile": "timer", "control": "eta" } }
  }
}

Set "liveActivity": true (or live.activity.start to onConnect or remote) or nothing starts. The relay pushes the island directly, so it keeps updating while the app is closed or force-quit.

Regions

Region Takes Default
compactLeading exactly one tile layout icon, bounces on update
compactTrailing exactly one tile hero value, ring or dot
minimal exactly one tile freshness ring around the connection dot
expanded.leading / .trailing / .center one tile (a scene is accepted but the sides are narrow) icon + title / freshness / the LIVE session clock
expanded.bottom a scene hero + slot chips + hero sparkline + two controls

The compact regions are a few points wide (the trailing one about 56 pt): use a ring, light, icon, timer or short value, never a gauge with a label. Keep expanded.bottom to two rows: the island has a hard height budget and clips. Interactive tiles fit about two in the bottom region.

Hard limits from iOS: 4 KB of state per update, 8 hours maximum per session, and the user can turn Live Activities off per app. Custom withAnimation is ignored; use the tile effect and transition fields and the self-ticking timer and ring.

Liveness

Pick a live.tier, then override single fields if you must.

Tier Live Activity (in app / remote) Widgets Controls Cost
realtime 1 s / 2 s, immediate pushed on change, 60 s apart at most pushed on change burns budgets; genuinely live sessions only
fresh (default) 1 s / 5 s, immediate pushed on change, 5 min apart at most pushed on change safe indefinitely
periodic 1 s / 30 s, opportunistic pulled every pullEvery (15 min) pulled on system reload near zero
manual app-driven app-driven app-driven the v1 behaviour

Floors are enforced by the app and the relay (cadence 1 s, remote cadence 2 s, widget reload spacing 60 s, widget pull 300 s, stale window 30 s); a lower value is raised to the floor and the connection console says so. A surface always shows its age: a stale window ends the LIVE clock and greys the freshness dot.

Constraints

The frontmatter constraints block holds all of the above as JSON: region tile limits, the 4 KB / 8 h limits, the allowed tile kinds, the tier table and every floor. SurfaceSceneValidator reports more than one tile in a side region and a tile that cannot fit its columns.

Generated from ControlDocs/live-activity.md. Something unclear or missing? Tell me.