You're in another app and there's a timer counting down at the top of your phone. You lock the screen and the same timer is sitting there. You swipe down to the Notification Center and it's there too, still ticking. It looks like a notification, but a notification can't tick.
That's a Live Activity. It looks like three different surfaces (Dynamic Island, lock-screen banner, Notification Center entry), but they're the same widget, rendered three ways by the OS. I wired one up for Tomoe, a focus timer I built. The punch line: it took a weekend. Most of that weekend was unlearning what I thought a Live Activity was. Once the shape clicked, the code was small.
This post is the shape.
What a Live Activity actually is
Three things that get glossed over in most tutorials:
It's a widget, not a notification. The view code lives in a Widget Extension target, separate from your app. The app pushes state; the extension renders pixels. If you've shipped a Home Screen widget before, this is the same story.
It's driven by a typed ContentState. You declare a Codable struct of "things that change" and call .update() with a new instance. There's no general "set arbitrary text" API. The schema is the contract.
The OS renders the timer. If you reach for Timer or a 1-second TimelineView, you're already off the path. SwiftUI's Text(timerInterval:countsDown:) lets the OS rasterise the countdown for you. Your widget doesn't wake every second. It can't; the budget would never allow it.
Two pieces of plumbing before any of this works. Declare NSSupportsLiveActivities in the app's Info.plist:
<key>NSSupportsLiveActivities</key>
<true/>
…and target iOS 16.2 or later. The 16.0 / 16.1 ActivityKit surface churned, and the workarounds aren't worth it.
The data model
Every Live Activity is keyed by an ActivityAttributes type. You split it into "stuff that's fixed for the life of the activity" (the attributes themselves) and "stuff that changes" (the nested ContentState).
Tomoe's looks like this:
public struct TomoeActivityAttributes: ActivityAttributes {
public struct ContentState: Codable, Hashable {
public var endDate: Date
public var isPaused: Bool
public var pausedRemainingSeconds: Int
}
public var task: String
}
The task name doesn't change once a session starts, so it's an attribute. The end timestamp, pause flag, and the snapshot for rendering paused state all change, so they're in ContentState. Codable + Hashable is how the OS serialises state across the app/widget process boundary.
The detail that costs everyone an afternoon: this file has to be a member of both targets, the app target and the widget extension target. Xcode won't warn you. The activity will start, and then the widget will silently fail to decode the state and render nothing. Check the file inspector before you debug anything else.
The four Dynamic Island slots
Here's where the mental model clicks. The DynamicIsland { … } builder gives you four slots, each for a different state of the same activity:
-
compactLeadingandcompactTrailing: the two tiny views you see hugging the camera cutout when only your activity is active. -
minimal: what you're demoted to when another app also has an active Live Activity. You're now a circle next to a dot. -
expanded: what the user sees when they long-press.
Plus the lock-screen / Notification Center view, which is the top-level body of the ActivityConfiguration. The same view code renders in both places. The OS just changes the chrome around it.
Trimmed to the load-bearing parts, Tomoe's whole widget is:
struct TomoeWidgetLiveActivity: Widget {
var body: some WidgetConfiguration {
ActivityConfiguration(for: TomoeActivityAttributes.self) { context in
LockScreenView(context: context)
.activityBackgroundTint(cream)
.activitySystemActionForegroundColor(ink)
} dynamicIsland: { context in
DynamicIsland {
DynamicIslandExpandedRegion(.leading) { /* mark + task name */ }
DynamicIslandExpandedRegion(.trailing) {
TimerView(state: context.state, fontSize: 38, color: .white)
}
DynamicIslandExpandedRegion(.bottom) {
if context.state.isPaused { Text("paused") }
}
} compactLeading: {
TomoeMark(size: 22)
} compactTrailing: {
TimerView(state: context.state, fontSize: 22, color: .white)
} minimal: {
TomoeMark(size: 20)
}
.keylineTint(accent)
}
}
}
Two things to keep in mind.
The compact regions are tiny. Tomoe's brand mark is 22pt; the trailing timer is 22pt at a minimum width of 56pt. Anything bigger overflows. Design for ~40pt of width and treat anything more as a bonus.
The minimal view appears without warning, the moment any other app starts an activity. Don't put information in compactLeading that needs to also be in minimal. Those are different layers, and you don't get a transition between them.
Let the OS tick
The single most useful API in this whole stack:
Text(timerInterval: Date()...state.endDate, countsDown: true)
.monospacedDigit()
You give it a date range; you get back a Text that the OS counts down for you. It updates without your widget doing anything. This is what makes the timer feel native: no flicker, no off-by-one, no battery cost.
The catch: you can't pause it. The OS counts to the end of the range, period. So when the user pauses, Tomoe swaps to a static label:
if state.isPaused {
Text(pausedTimeString(seconds: state.pausedRemainingSeconds))
} else {
Text(timerInterval: Date()...state.endDate, countsDown: true)
}
On pause, I push an update with isPaused: true and a snapshot of the remaining seconds. The widget renders that snapshot until the next state change. On resume, I push a new endDate = now + remaining and we're back on the OS-driven interval.
pausedRemainingSeconds is the non-obvious part: I have to send the value the widget should display, because the widget process has no idea how long ago I paused.
Pushing updates from the app
The lifecycle is three calls. From Tomoe's bridge module, trimmed:
let activity = try Activity.request(
attributes: attributes,
content: .init(state: state, staleDate: nil),
pushType: nil
)
// later, on pause/resume
await activity.update(.init(state: newState, staleDate: nil))
// done
await activity.end(nil, dismissalPolicy: .immediate)
pushType: nil means "I'll push state from this app process." That's right for a timer. The app already knows when the user paused or finished. The other option is .token, which lets you push from a server via APNs. Useful for Uber-style "your driver is here" updates that the app itself can't observe; overkill for anything the foreground app can drive.
The budget you should know about, so you don't design something that fights it:
- An activity can live for about 8 hours before the OS forces it stale.
-
ContentStateis capped at ~4 KB encoded. - Updates are rate-limited; push every 100ms and the OS quietly drops most of them.
- A stale activity dims on the lock screen but doesn't disappear until you call
.end()or the user dismisses it.
That last one matters more than it sounds: passing an endDate in the past does not auto-end the activity. The countdown will show 00:00 and just sit there. You have to call .end() yourself when the timer reaches zero. In Tomoe I do this from the JS layer when the timer fires, since the app is React Native. But the Swift Activity.request / .update / .end API is the same regardless of host. Flutter, RN, native, doesn't matter; the shape is identical.
Things that bit me
Shared types break easily. The ActivityAttributes file has to belong to both targets. Add → File Inspector → check both Target Memberships. If your activity starts but the widget renders empty, this is it. Every time.
Dynamic Island regions ignore overflow. SwiftUI happily lets you put a wide view in compactTrailing. The OS will clip it without a warning at build time. Use .minimumScaleFactor(0.6) and .lineLimit(1) defensively, especially on numeric content where the digit count varies.
Asset catalogs are flaky in widget extensions. I had a brand image that loaded fine in the simulator and failed silently on device. I switched to a SwiftUI-drawn mark (a coloured rectangle with an SF Symbol on top) and the problem went away. If a widget asset isn't appearing on a real iPhone, that's the first thing to try.
Closing
What surprised me about Live Activities is how little there is to them once you've named the parts. A typed ContentState, four Dynamic Island slots, one OS-driven timer view, three lifecycle calls. That's the whole API surface for a focus timer. Most of the hard work happens before you write code: deciding what to put in the compact view, what's worth a long-press to expand, what the paused state should feel like.
I built Tomoe to scratch my own itch for a focus timer that doesn't shout. Three calm scenes: rain, stars, fireflies. Four session lengths. No accounts, no tracking, no streaks to break. The timer follows you out of the app, into the Dynamic Island and onto the lock screen, exactly the way this post describes. Available on the App Store.