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
Field
Type
Default
What it does
liveActivityliveActivity
on / 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.
compactLeadingcompactLeading
object
—
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.
compactTrailingcompactTrailing
object
—
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.
minimalminimal
object
—
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.
expandedexpanded
object
—
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.
keylinekeyline
text
—
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.tier
choiceone of 4
fresh
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
freshdefaultlive 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.cadence
number1–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.
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.