Adding Live Activities to a Pomodoro timer: what the docs don't tell you

A countdown timer is the perfect use case for Live Activities — and also a great way to discover everything the ActivityKit docs gloss over. When I added Live Activities to Cadento, my SwiftUI Pomodoro app, the "happy path" took an afternoon. The edge cases took a lot longer.

Here's the practical version: what actually matters when you put a focus timer on the lock screen and the Dynamic Island.

The mental model

A Live Activity has three things you define:

1. 
   ActivityAttributes — the static data, fixed for the lifetime of the activity (e.g. the session's total duration, the task name).


2. 
   ContentState — the dynamic data that changes over time (e.g. whether it's running or paused).


3. 
   The SwiftUI views — lock screen, Dynamic Island expanded/compact/minimal.
   

struct TimerActivityAttributes: ActivityAttributes {

    // static for the whole activity

    let sessionName: String

    let endDate: Date



    struct ContentState: Codable, Hashable {

        // changes over time

        var isPaused: Bool

        var pausedRemaining: TimeInterval?

    }

}

The single biggest "aha" is the next section.

Don't push every second. Let the system count.

The instinct is to update the activity every second so the number ticks down. Don't. You'll hit update throttling and drain battery, and it's unnecessary.

Instead, hand SwiftUI a date range and let it render the countdown itself:

// in the lock screen / Dynamic Island view

Text(timerInterval: context.attributes.startDate...context.attributes.endDate,

     countsDownFrom: 0)

    .monospacedDigit()

Text(timerInterval:) renders a live-updating timer without any activity updates at all. You only push an update when something semantic changes — pause, resume, or finish. That turns "60 updates a minute" into "an update when the user actually does something."

For pause, you stop the auto-counting text and show the frozen remaining time from ContentState.pausedRemaining. That's the whole trick.

The Dynamic Island has four presentations, not one

You must provide all of these, and they're genuinely different layouts:

DynamicIsland {

    // EXPANDED — long-press / when it's the active activity

    DynamicIslandExpandedRegion(.leading)  { /* icon */ }

    DynamicIslandExpandedRegion(.trailing) { /* time  */ }

    DynamicIslandExpandedRegion(.center)   { /* label */ }

    DynamicIslandExpandedRegion(.bottom)   { /* progress */ }

} compactLeading: {

    Image(systemName: "timer")

} compactTrailing: {

    Text(timerInterval: range, countsDownFrom: 0).monospacedDigit()

} minimal: {

    Image(systemName: "timer")

}

Gotchas I hit:

• 
  Compact trailing has almost no width. A full mm:ss can clip next to other activities. Keep it tight, use .monospacedDigit(), and test with another Live Activity running.


• 
  Minimal is a single glyph. Don't try to fit text. It shows when multiple activities are active.


• 
  Tap targets: the whole thing deep-links into your app via widgetURL — wire it up so a tap opens the running timer, not the home screen.

Starting, updating, ending

// start

let activity = try Activity.request(

    attributes: attributes,

    content: .init(state: initialState, staleDate: nil),

    pushType: nil          // local; no push server needed for a timer

)



// update (only on pause/resume/etc.)

await activity.update(.init(state: newState, staleDate: nil))



// end — choose a dismissal policy

await activity.end(.init(state: finalState, staleDate: nil),

                   dismissalPolicy: .after(.now + 4))   // linger 4s, then clear

Notes from shipping it:

• A timer is local — pushType: nil. You do not need a push server. (Push-driven Live Activities are for server-side events like delivery tracking.)


• 
  dismissalPolicy matters. .immediate yanks it the instant the session ends, which feels abrupt. A short .after(...) lets the user see "Done" before it disappears.


• 
  Reconnect on launch. When the app comes back, iterate Activity<TimerActivityAttributes>.activities to find and re-attach to an in-flight activity instead of orphaning it.

The things that actually bit me

• 
  Permission can be off. Users can disable Live Activities globally or per-app. Check ActivityAuthorizationInfo().areActivitiesEnabled and degrade gracefully — don't assume request() will succeed.


• 
  The widget extension is a separate target. Your Live Activity views live in the widget extension, so shared model code must be in a target both can see, or you'll duplicate types.


• 
  Background time is not yours. You can't run a precise in-app timer in the background to drive updates. The whole point of Text(timerInterval:) is that the system renders the countdown — lean on it instead of fighting the background execution model.


• 
  Localize it. Cadento ships in 39 languages; the Live Activity is on-screen text like any other UI, so "Focus" / "Break" / "Paused" all go through the String Catalog too. Easy to forget because it's not in the main app's view tree.

Was it worth it?

For a focus timer, absolutely — it's the feature that makes the app feel present. The session lives on your lock screen and in the Dynamic Island, so you glance and know exactly where you are without opening anything. That's the entire promise of a Pomodoro app, surfaced at the OS level.

The key shift in thinking: you're not driving an animation, you're declaring state and letting the system render time. Once that clicks, Live Activities stop fighting you.

I'm a solo iOS developer from Japan building small, deeply localized apps. Cadento (focus timer, 39 languages, with Live Activities, widgets and an Apple Watch app) is on the App Store. Questions welcome in the comments.