Alarmkit

AlarmKit

Schedule prominent alarms and countdown timers that surface on the Lock Screen, Dynamic Island, StandBy, and a paired Apple Watch when the alarm fires. AlarmKit requires iOS 26+ / iPadOS 26+. Alarms can break through Focus and Silent mode.

AlarmKit uses ActivityKit data models for its Live Activity, but the firing alert is system-managed alarm UI, not a general custom notification UI surface. Custom UI belongs only to countdown and paused Live Activity states rendered by a Widget Extension with the same AlarmAttributes<Metadata> and AlarmPresentationState used when scheduling.

See references/alarmkit-patterns.md for complete code patterns including authorization, scheduling, countdown timers, snooze handling, and widget setup.

import AlarmKit

Contents

• Workflow
• Authorization
• Alarm vs Timer Decision
• Scheduling Alarms
• Countdown Timers
• Alarm States
• AlarmAttributes and AlarmPresentation
• AlarmButton
• Live Activity Integration
• Common Mistakes
• Review Checklist
• References

Workflow

1. Create a new alarm or timer

1. Add NSAlarmKitUsageDescription to Info.plist with a user-facing string.
2. Request authorization with AlarmManager.shared.requestAuthorization() when the app can explain the value, or handle the first-schedule system prompt.
3. If authorization is .denied or not .authorized, show recovery UI instead of scheduling.
4. Configure AlarmPresentation (alert, countdown, paused states).
5. Create AlarmAttributes with the presentation, optional metadata, and tint color.
6. Build an AlarmManager.AlarmConfiguration (.alarm or .timer).
7. Schedule with AlarmManager.shared.schedule(id:configuration:).
8. Observe alarmManager.alarmUpdates and confirm the scheduled ID reaches the expected state.
9. If using countdown, add a Widget Extension target with an ActivityConfiguration for the same AlarmAttributes<Metadata> type.

2. Review existing alarm code

Run through the Review Checklist at the end of this document.

Authorization

AlarmKit requires user authorization. Request early when the app can explain the value, or let AlarmKit prompt automatically on first schedule. If authorization is not granted after the explicit or automatic prompt, alarms are not scheduled and will not alert.

let manager = AlarmManager.shared

// Request authorization explicitly
let state = try await manager.requestAuthorization()
guard state == .authorized else { return }

// Check current state synchronously
let current = manager.authorizationState // .authorized, .denied, .notDetermined

// Observe authorization changes
for await state in manager.authorizationUpdates {
    switch state {
    case .authorized: print("Alarms enabled")
    case .denied:     print("Alarms disabled")
    case .notDetermined: break
    @unknown default: break
    }
}

Alarm vs Timer Decision

Use .alarm(schedule:...) when firing at a clock time. Use .timer(duration:...) when firing after a duration from now.

Scheduling Alarms

Alarm.Schedule

Use .fixed(date) for a one-time absolute date or .relative for a local clock time with .never or .weekly repetition. Load Recurring Alarm Patterns for daily, weekday, weekend, and fixed-date variants.

Schedule and Configure

let id = UUID()

let alert = AlarmPresentation.Alert(
    title: "Wake Up",
    secondaryButton: AlarmButton(
        text: "Snooze", textColor: .white, systemImageName: "bell.slash"
    ),
    secondaryButtonBehavior: .countdown
)
let presentation = AlarmPresentation(alert: alert)
struct EmptyAlarmMetadata: AlarmMetadata {}
let attributes = AlarmAttributes<EmptyAlarmMetadata>(
    presentation: presentation,
    metadata: nil,
    tintColor: .indigo
)

let snooze = Alarm.CountdownDuration(preAlert: nil, postAlert: 300)
let configuration = AlarmManager.AlarmConfiguration(
    countdownDuration: snooze,
    schedule: .relative(.init(
        time: .init(hour: 7, minute: 0),
        repeats: .never
    )),
    attributes: attributes,
    sound: .default
)

let alarm = try await AlarmManager.shared.schedule(
    id: id,
    configuration: configuration
)

For an authorization-gated function and metadata-bearing variant, load Complete Alarm Scheduling Flow.

stopIntent and secondaryIntent default to nil. Omit stopIntent for AlarmKit's standard system Stop behavior; provide it only when Stop must run app cleanup, custom stop behavior, or other side effects. Omit secondaryIntent for ordinary Snooze/Repeat with secondaryButtonBehavior: .countdown and Alarm.CountdownDuration.postAlert; provide it only for .custom secondary behavior or app cleanup/custom behavior.

Alarm State Transitions

cancel(id:)
    |
scheduled --> countdown --> alerting
    |             |             |
    |         pause(id:)    stop(id:) / countdown(id:)
    |             |
    |         paused ----> countdown (via resume(id:))
    |
cancel(id:) removes from system entirely

• cancel(id:) -- remove the alarm completely, including repeating alarms
• pause(id:) -- pause a counting-down alarm; throws from other states
• resume(id:) -- resume a paused alarm; throws from other states
• stop(id:) -- stop the alarm; one-shot alarms are removed, repeating alarms reschedule
• countdown(id:) -- restart countdown from alerting state (snooze); throws from other states

Countdown Timers

Timers fire after a duration and always show a countdown UI. Use Alarm.CountdownDuration to control pre-alert and post-alert durations.

CountdownDuration

Alarm.CountdownDuration controls the visible countdown phases:

• preAlert -- seconds to count down before the alarm fires (the main countdown)
• postAlert -- seconds for a repeat/snooze countdown after the alarm fires

Load Complete Countdown Timer Flow for the timer factory, pause/resume presentation, metadata, and scheduling gate.

Alarm States

Each Alarm has a state property reflecting its current lifecycle position.

Observing State Changes

AlarmManager.shared.alarms is a throwing getter for the current daemon snapshot. Use try, and either propagate the error or wrap launch refresh in do/catch before relying on the snapshot.

Observe alarmUpdates rather than maintaining an independent lifecycle. Load State Observation with Async Sequences for the complete store and refresh loop.

An alarm that disappears from alarmUpdates is no longer scheduled with AlarmKit. Compare against app-persisted IDs when you need to distinguish fired, cancelled, and rescheduled alarms.

AlarmAttributes and AlarmPresentation

AlarmAttributes conforms to ActivityAttributes and defines the static data for the alarm's Live Activity. It is generic over a Metadata type