/alarmkit

name: alarmkit
description: "Implement AlarmKit alarms and countdown timers for iOS and iPadOS with Lock Screen, Dynamic Island, StandBy, and paired Apple Watch system UI. Covers AlarmManager scheduling, AlarmAttributes and AlarmPresentation, system Stop and AlarmButton secondary actions, authorization, state observation, countdown widget-extension handoff, and Live Activity integration. Use when building wake-up alarms, countdown timers, or alarm-style alerts that need Apple's system alarm experience."

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](references/alarmkit-patterns.md) for complete code patterns including authorization, scheduling, countdown timers, snooze handling, and widget setup.

import AlarmKit

Contents

• [Workflow](#workflow)
• [Authorization](#authorization)
• [Alarm vs Timer Decision](#alarm-vs-timer-decision)
• [Scheduling Alarms](#scheduling-alarms)
• [Countdown Timers](#countdown-timers)
• [Alarm States](#alarm-states)
• [AlarmAttributes and AlarmPresentation](#alarmattributes-and-alarmpresentation)
• [AlarmButton](#alarmbutton)
• [Live Activity Integration](#live-activity-integration)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#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

| Feature | Alarm (`.alarm`) | Timer (`.timer`) | |---|---|---| | Fires at | Specific time (schedule) | After duration elapses | | Countdown UI | Optional | Always shown | | Recurring | Yes (weekly days) | No | | Use case | Wake-up, scheduled reminders | Cooking, workout intervals |

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](references/alarmkit-patterns.md#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](references/alarmkit-patterns.md#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:)
    |
schedu