Alarmkit

AlarmKit

Schedule prominent alarms and countdown timers that surface on the Lock Screen, Dynamic Island, and Apple Watch. AlarmKit requires iOS 26+ / iPadOS 26+. Alarms override Focus and Silent mode automatically.

AlarmKit builds on Live Activities -- every alarm creates a system-managed Live Activity with templated UI. You configure the presentation via AlarmAttributes and AlarmPresentation rather than building custom widget views.

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(). 3. Configure AlarmPresentation (alert, countdown, paused states). 4. Create AlarmAttributes with the presentation, optional metadata, and tint color. 5. Build an AlarmManager.AlarmConfiguration (.alarm or .timer). 6. Schedule with AlarmManager.shared.schedule(id:configuration:). 7. Observe state changes via alarmManager.alarmUpdates. 8. If using countdown, add a widget extension target for non-alerting Live Activity UI.

2. Review existing alarm code

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

Authorization

AlarmKit requires explicit user authorization. Without it, alarms silently fail to schedule. Request early (e.g., at onboarding) or let AlarmKit prompt automatically on first schedule.

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

Alarms use Alarm.Schedule to define when they fire.

// Fixed: fire at an exact Date (one-time only)
let fixed: Alarm.Schedule = .fixed(myDate)

// Relative one-time: fire at 7:30 AM in device time zone, no repeat
let oneTime: Alarm.Schedule = .relative(.init(
    time: .init(hour: 7, minute: 30),
    repeats: .never
))

// Recurring: fire at 6:00 AM on weekdays
let weekday: Alarm.Schedule = .relative(.init(
    time: .init(hour: 6, minute: 0),
    repeats: .weekly([.monday, .tuesday, .wednesday, .thursday, .friday])
))

Schedule and Configure

let id = UUID()

let configuration = AlarmManager.AlarmConfiguration.alarm(
    schedule: .relative(.init(
        time: .init(hour: 7, minute: 0),
        repeats: .never
    )),
    attributes: attributes,
    stopIntent: StopAlarmIntent(alarmID: id.uuidString),
    secondaryIntent: SnoozeIntent(alarmID: id.uuidString),
    sound: .default
)

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

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 (any state)
• pause(id:) -- pause a counting-down alarm
• resume(id:) -- resume a paused alarm
• stop(id:) -- stop an alerting alarm
• countdown(id:) -- restart countdown from alerting state (snooze)

Countdown Timers

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

// Simple timer: 5-minute countdown, no snooze
let timerConfig = AlarmManager.AlarmConfiguration.timer(
    duration: 300,
    attributes: attributes,
    stopIntent: StopTimerIntent(timerID: id.uuidString),
    sound: .default
)

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

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

let countdown = Alarm.CountdownDuration(
    preAlert: 600,   // 10-minute countdown before alert
    postAlert: 300   // 5-minute snooze countdown if user taps Repeat
)

let config = AlarmManager.AlarmConfiguration(
    countdownDuration: countdown,
    schedule: .relative(.init(
        time: .init(hour: 8, minute: 0),
        repeats: .never
    )),
    attributes: attributes,
    stopIntent: stopIntent,
    secondaryIntent: snoozeIntent,
    sound: .default
)

Alarm States

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

Observing State Changes

let manager = AlarmManager.shared

// Get all current alarms
let alarms = manager.alarms

// Observe changes as an async sequence
for await updatedAlarms in manager.alarmUpdates {
    for alarm in updatedAlarms {
        switch alarm.state {
        case .scheduled:  print("\(alarm.id) waiting")
        case .countdown:  print("\(alarm.id) counting down")
        case .paused:     print("\(alarm.id) paused")
        case .alerting:   print("\(alarm.id) alerting!")
        @unknown default: break
        }
    }
}

An alarm that disappears from alarmUpdates has been cancelled or fully stopped and is no longer tracked by the system.

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 conforming to AlarmMetadata.

AlarmPresentation

Defines the UI content for each alarm state. The system renders a templated Live Activity using this data -- you do not build custom SwiftUI views for the alarm itself.

// Alert state (required) -- shown when alarm is firing
let alert = AlarmPresentation.Alert(
    title: "Wake Up",
    secondaryButton: AlarmButton(
        text: "Snooze",
        textColor: .white,
        systemImageName: "bell.slash"
    ),
    secondaryButtonBehavior: .countdown  // snooze restarts countdown
)

// Countdown state (optional) -- shown during pre-alert countdown
let countdown = AlarmPresentation.Countdown(
    title: "Morning Alarm",
    pauseButton: AlarmButton(
        text: "Pause",
        textColor: .orange,
        systemImageName: "pause.fill"
    )
)

// Paused state (optional) -- shown when countdown is paused
let paused = AlarmPresentation.Paused(
    title: "Paused",
    resumeButton: AlarmButton(
        text: "Resume",
        textColor: .green,
        systemImageName: "play.fill"
    )
)

let presentation = AlarmPresentation(
    alert: alert,
    countdown: countdown,
    paused: paused
)

AlarmAttributes

struct CookingMetadata: AlarmMetadata {
    var recipeName: String
    var stepNumber: Int
}

let attributes = AlarmAttributes(
    presentation: presentation,
    metadata: CookingMetadata(recipeName: "Pasta", stepNumber: 3),
    tintColor: .blue
)

AlarmPresentationState

AlarmPresentationState is the system-managed ContentState of the alarm Live Activity. It contains the alarm ID and a Mode enum:

• .alert(Alert) -- alarm is firing, includes the scheduled time
• .countdown(Countdown) -- actively counting down, includes fire date and durations
• .paused(Paused) -- countdown paused, includes elapsed and total durations

The widget extension reads AlarmPresentationState.mode to decide which UI to render in the Dynamic Island and Lock Screen for non-alerting states.

AlarmButton

AlarmButton defines the appearance of action buttons in the alarm UI.

let stopButton = AlarmButton(
    text: "Stop",
    textColor: .red,
    systemImageName: "stop.fill"
)

let snoozeButton = AlarmButton(
    text: "Snooze",
    textColor: .white,
    systemImageName: "bell.slash"
)

Secondary Button Behavior

The secondary button on the alert UI has two behaviors:

Live Activity Integration

AlarmKit alarms automatically appear as Live Activities on the Lock Screen and Dynamic Island on iPhone, and in the Smart Stack on Apple Watch. The system manages the alerting UI. For countdown and paused states, add a widget extension that reads AlarmAttributes and AlarmPresentationState.

A widget extension is required if your alarm uses countdown presentation. Without it, the system may dismiss alarms unexpectedly.

struct AlarmWidgetBundle: WidgetBundle {
    var body: some Widget {
        AlarmActivityWidget()
    }
}

struct AlarmActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: AlarmAttributes<CookingMetadata>.self) { context in
            // Lock Screen presentation for countdown/paused states
            AlarmLockScreenView(context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.center) {
                    Text(context.attributes.presentation.alert.title)
                }
                DynamicIslandExpandedRegion(.bottom) {
                    // Show countdown or paused info based on mode
                    AlarmExpandedView(state: context.state)
                }
            } compactLeading: {
                Image(systemName: "alarm.fill")
            } compactTrailing: {
                AlarmCompactTrailing(state: context.state)
            } minimal: {
                Image(systemName: "alarm.fill")
            }
        }
    }
}

Common Mistakes

DON'T: Forget NSAlarmKitUsageDescription in Info.plist. DO: Add a descriptive usage string. Without it, AlarmKit cannot schedule alarms at all.

DON'T: Skip authorization and assume alarms will schedule. DO: Call requestAuthorization() early and handle .denied gracefully.

DON'T: Use .timer when you need a recurring schedule. DO: Use .alarm with .weekly([...]) for recurring alarms. Timers are one-shot.

DON'T: Omit the widget extension when using countdown presentation. DO: Add a widget extension target. AlarmKit requires it for countdown/paused Live Activity UI. Why: Without a widget extension, the system may dismiss alarms before they alert.

DON'T: Ignore alarmUpdates and track alarm state manually. DO: Observe alarmManager.alarmUpdates to stay synchronized with the system. Why: Alarm state can change while your app is backgrounded.

DON'T: Forget to provide a stopIntent -- it cannot be nil in practice. DO: Always provide a LiveActivityIntent for stop so the button performs cleanup.

DON'T: Store large data in AlarmMetadata. It is serialized with the Live Activity. DO: Keep metadata lightweight. Store large data in your app and reference by ID.

DON'T: Use deprecated stopButton parameter on AlarmPresentation.Alert. DO: Use the current init(title:secondaryButton:secondaryButtonBehavior:) initializer.

Review Checklist

• [ ] NSAlarmKitUsageDescription present in Info.plist with non-empty string
• [ ] Authorization requested and .denied state handled in UI
• [ ] AlarmPresentation covers all relevant states (alert, countdown, paused)
• [ ] Widget extension target added if countdown presentation is used
• [ ] AlarmAttributes metadata type conforms to AlarmMetadata
• [ ] Alarm ID stored for later cancel/pause/resume/stop operations
• [ ] alarmUpdates async sequence observed to track state changes
• [ ] stopIntent and secondaryIntent are valid LiveActivityIntent implementations
• [ ] postAlert duration set on CountdownDuration if snooze (.countdown behavior) is used
• [ ] Tint color set on AlarmAttributes to differentiate from other apps
• [ ] Error handling for AlarmManager.AlarmError.maximumLimitReached
• [ ] Tested on device (alarm sound/vibration differs from Simulator)

References

• Patterns and code: references/alarmkit-patterns.md
• Apple docs: AlarmKit |

AlarmManager | AlarmAttributes | Scheduling an alarm

AlarmKit Patterns

Complete implementation patterns for AlarmKit alarms, countdown timers, authorization, state observation, and Live Activity integration. All patterns target iOS 26+ / iPadOS 26+ with Swift 6.3.

Contents

• Complete Alarm Scheduling Flow
• Complete Countdown Timer Flow
• Authorization Manager
• State Observation with Async Sequences
• Live Activity Widget Extension for Alarms
• Recurring Alarm Patterns
• Snooze and Dismiss Handling
• Info.plist Configuration
• Error Handling
• Apple Documentation Links

Complete Alarm Scheduling Flow

End-to-end pattern for scheduling a wake-up alarm with snooze support.

import AlarmKit
import AppIntents

struct StopAlarmIntent: LiveActivityIntent {
    static var title: LocalizedStringResource = "Stop Alarm"
    @Parameter(title: "Alarm ID") var alarmID: String
    init() {}
    init(alarmID: String) { self.alarmID = alarmID }
    func perform() async throws -> some IntentResult {
        try AlarmManager.shared.stop(id: UUID(uuidString: alarmID)!)
        return .result()
    }
}

struct SnoozeAlarmIntent: LiveActivityIntent {
    static var title: LocalizedStringResource = "Snooze Alarm"
    @Parameter(title: "Alarm ID") var alarmID: String
    init() {}
    init(alarmID: String) { self.alarmID = alarmID }
    func perform() async throws -> some IntentResult {
        try AlarmManager.shared.countdown(id: UUID(uuidString: alarmID)!)
        return .result()
    }
}

struct WakeUpMetadata: AlarmMetadata {
    var label: String
}

@MainActor
func scheduleWakeUpAlarm(
    hour: Int, minute: Int, label: String
) async throws -> Alarm {
    let manager = AlarmManager.shared
    let authState = try await manager.requestAuthorization()
    guard authState == .authorized else { throw AlarmSchedulingError.notAuthorized }

    let alert = AlarmPresentation.Alert(
        title: LocalizedStringResource(stringLiteral: label),
        secondaryButton: AlarmButton(
            text: "Snooze", textColor: .white, systemImageName: "bell.slash"
        ),
        secondaryButtonBehavior: .countdown
    )
    let presentation = AlarmPresentation(alert: alert)
    let attributes = AlarmAttributes(
        presentation: presentation,
        metadata: WakeUpMetadata(label: label),
        tintColor: .indigo
    )

    let id = UUID()
    let config = AlarmManager.AlarmConfiguration.alarm(
        schedule: .relative(.init(
            time: .init(hour: hour, minute: minute), repeats: .never
        )),
        attributes: attributes,
        stopIntent: StopAlarmIntent(alarmID: id.uuidString),
        secondaryIntent: SnoozeAlarmIntent(alarmID: id.uuidString),
        sound: .default
    )
    return try await manager.schedule(id: id, configuration: config)
}

enum AlarmSchedulingError: Error {
    case notAuthorized
}

Complete Countdown Timer Flow

End-to-end pattern for a countdown timer with pause/resume support.

import AlarmKit
import AppIntents

struct StopTimerIntent: LiveActivityIntent {
    static var title: LocalizedStringResource = "Stop Timer"
    @Parameter(title: "Timer ID") var timerID: String
    init() {}
    init(timerID: String) { self.timerID = timerID }
    func perform() async throws -> some IntentResult {
        try AlarmManager.shared.stop(id: UUID(uuidString: timerID)!)
        return .result()
    }
}

struct CookingTimerMetadata: AlarmMetadata {
    var recipeName: String
    var stepDescription: String
}

@MainActor
func startCookingTimer(
    durationSeconds: TimeInterval, recipeName: String, step: String
) async throws -> Alarm {
    let manager = AlarmManager.shared
    let authState = try await manager.requestAuthorization()
    guard authState == .authorized else { throw AlarmSchedulingError.notAuthorized }

    let alert = AlarmPresentation.Alert(
        title: LocalizedStringResource(stringLiteral: "\(recipeName): \(step)"),
        secondaryButton: nil, secondaryButtonBehavior: nil
    )
    let countdown = AlarmPresentation.Countdown(
        title: LocalizedStringResource(stringLiteral: recipeName),
        pauseButton: AlarmButton(
            text: "Pause", textColor: .orange, systemImageName: "pause.fill"
        )
    )
    let paused = AlarmPresentation.Paused(
        title: "Paused",
        resumeButton: AlarmButton(
            text: "Resume", textColor: .green, systemImageName: "play.fill"
        )
    )
    let presentation = AlarmPresentation(
        alert: alert, countdown: countdown, paused: paused
    )
    let attributes = AlarmAttributes(
        presentation: presentation,
        metadata: CookingTimerMetadata(recipeName: recipeName, stepDescription: step),
        tintColor: .orange
    )

    let id = UUID()
    let config = AlarmManager.AlarmConfiguration.timer(
        duration: durationSeconds,
        attributes: attributes,
        stopIntent: StopTimerIntent(timerID: id.uuidString),
        sound: .default
    )
    return try await manager.schedule(id: id, configuration: config)
}

Authorization Manager

Observable pattern for centralized authorization management.

import AlarmKit
import Observation

@Observable
@MainActor
final class AlarmAuthorizationManager {
    private let manager = AlarmManager.shared
    private(set) var isAuthorized = false
    private(set) var authState: AlarmManager.AuthorizationState = .notDetermined

    init() {
        authState = manager.authorizationState
        isAuthorized = authState == .authorized
    }

    func requestIfNeeded() async throws -> Bool {
        guard authState == .notDetermined else { return isAuthorized }
        let state = try await manager.requestAuthorization()
        authState = state
        isAuthorized = state == .authorized
        return isAuthorized
    }

    func observeAuthorizationChanges() async {
        for await state in manager.authorizationUpdates {
            authState = state
            isAuthorized = state == .authorized
        }
    }
}

// Usage in SwiftUI
struct AlarmSettingsView: View {
    @State private var authManager = AlarmAuthorizationManager()

    var body: some View {
        Group {
            if authManager.isAuthorized {
                Text("Alarms are enabled")
            } else if authManager.authState == .denied {
                ContentUnavailableView(
                    "Alarms Disabled", systemImage: "alarm.waves.left.and.right",
                    description: Text("Enable in Settings > Your App > Alarms & Timers.")
                )
            } else {
                Button("Enable Alarms") {
                    Task { try? await authManager.requestIfNeeded() }
                }
            }
        }
        .task { await authManager.observeAuthorizationChanges() }
    }
}

State Observation with Async Sequences

Pattern for tracking all alarms and reacting to state changes.

import AlarmKit
import Observation

@Observable
@MainActor
final class AlarmStore {
    private let manager = AlarmManager.shared
    private(set) var alarms: [Alarm] = []

    init() { alarms = manager.alarms }

    func startObserving() async {
        for await updatedAlarms in manager.alarmUpdates {
            alarms = updatedAlarms
        }
    }

    func alarm(for id: UUID) -> Alarm? { alarms.first { $0.id == id } }
    func alarms(in state: Alarm.State) -> [Alarm] { alarms.filter { $0.state == state } }

    func cancel(_ id: Alarm.ID) throws { try manager.cancel(id: id) }
    func pause(_ id: Alarm.ID) throws { try manager.pause(id: id) }
    func resume(_ id: Alarm.ID) throws { try manager.resume(id: id) }
    func stop(_ id: Alarm.ID) throws { try manager.stop(id: id) }
    func snooze(_ id: Alarm.ID) throws { try manager.countdown(id: id) }
}

// Usage in SwiftUI
struct AlarmListView: View {
    @State private var store = AlarmStore()

    var body: some View {
        List(store.alarms, id: \.id) { alarm in
            HStack {
                Text(alarm.id.uuidString.prefix(8)).font(.headline)
                Spacer()
                switch alarm.state {
                case .scheduled:
                    Button("Cancel", role: .destructive) { try? store.cancel(alarm.id) }
                case .countdown:
                    Button("Pause") { try? store.pause(alarm.id) }
                case .paused:
                    Button("Resume") { try? store.resume(alarm.id) }
                case .alerting:
                    Button("Stop") { try? store.stop(alarm.id) }
                @unknown default:
                    EmptyView()
                }
            }
        }
        .task { await store.startObserving() }
    }
}

Live Activity Widget Extension for Alarms

Widget extension that renders countdown and paused states. Required when your alarm uses countdown presentation.

import WidgetKit
import SwiftUI
import AlarmKit

// MARK: - Widget bundle

struct AlarmWidgetBundle: WidgetBundle {
    var body: some Widget {
        AlarmLiveActivityWidget()
    }
}

// MARK: - Live Activity configuration

struct AlarmLiveActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: AlarmAttributes<CookingTimerMetadata>.self) { context in
            AlarmLockScreenView(context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) {
                    Image(systemName: "alarm.fill")
                        .font(.title2)
                        .foregroundStyle(context.attributes.tintColor)
                }
                DynamicIslandExpandedRegion(.trailing) {
                    AlarmCountdownText(state: context.state)
                        .font(.title3.monospacedDigit())
                }
                DynamicIslandExpandedRegion(.center) {
                    Text(context.attributes.metadata?.recipeName ?? "Timer")
                        .font(.headline)
                }
                DynamicIslandExpandedRegion(.bottom) {
                    if let step = context.attributes.metadata?.stepDescription {
                        Text(step).font(.subheadline).foregroundStyle(.secondary)
                    }
                }
            } compactLeading: {
                Image(systemName: "alarm.fill").foregroundStyle(context.attributes.tintColor)
            } compactTrailing: {
                AlarmCountdownText(state: context.state)
                    .frame(width: 44).monospacedDigit()
            } minimal: {
                Image(systemName: "alarm.fill").foregroundStyle(context.attributes.tintColor)
            }
            .keylineTint(context.attributes.tintColor)
        }
    }
}

// MARK: - Lock Screen view

struct AlarmLockScreenView: View {
    let context: ActivityViewContext<AlarmAttributes<CookingTimerMetadata>>

    var body: some View {
        VStack(alignment: .leading) {
            HStack {
                Image(systemName: "alarm.fill")
                    .foregroundStyle(context.attributes.tintColor)
                Text(context.attributes.metadata?.recipeName ?? "Timer")
                    .font(.headline)
                Spacer()
                AlarmCountdownText(state: context.state)
                    .font(.title3.monospacedDigit().bold())
            }

            switch context.state.mode {
            case .countdown(let info):
                ProgressView(
                    value: info.previouslyElapsedDuration,
                    total: info.totalCountdownDuration
                )
                .tint(context.attributes.tintColor)
            case .paused:
                Label("Paused", systemImage: "pause.fill")
                    .font(.subheadline).foregroundStyle(.secondary)
            case .alert:
                EmptyView()  // System handles alerting UI
            @unknown default:
                EmptyView()
            }
        }
        .padding()
    }
}

// MARK: - Helper views

struct AlarmCountdownText: View {
    let state: AlarmPresentationState

    var body: some View {
        switch state.mode {
        case .countdown(let info):
            Text(info.fireDate, style: .timer)
        case .paused(let info):
            let remaining = info.totalCountdownDuration - info.previouslyElapsedDuration
            Text(Duration.seconds(remaining), format: .time(pattern: .minuteSecond))
        case .alert(let info):
            Text("\(info.time.hour):\(String(format: "%02d", info.time.minute))")
        @unknown default:
            Text("--:--")
        }
    }
}

Recurring Alarm Patterns

// Daily alarm (every day)
let dailySchedule = Alarm.Schedule.relative(.init(
    time: .init(hour: 7, minute: 0),
    repeats: .weekly([.sunday, .monday, .tuesday, .wednesday,
                      .thursday, .friday, .saturday])
))

// Weekday-only alarm
let weekdaySchedule = Alarm.Schedule.relative(.init(
    time: .init(hour: 6, minute: 30),
    repeats: .weekly([.monday, .tuesday, .wednesday, .thursday, .friday])
))

// Weekend alarm
let weekendSchedule = Alarm.Schedule.relative(.init(
    time: .init(hour: 9, minute: 0),
    repeats: .weekly([.saturday, .sunday])
))

// One-time alarm at a specific Date
let targetDate = Calendar.current.date(
    from: DateComponents(year: 2026, month: 6, day: 15, hour: 14, minute: 30)
)!
let fixedSchedule = Alarm.Schedule.fixed(targetDate)

Snooze and Dismiss Handling

Pattern for alarm with snooze (countdown behavior) and custom secondary action.

Snooze with countdown restart

func scheduleAlarmWithSnooze(
    hour: Int, minute: Int, snoozeDurationSeconds: TimeInterval
) async throws -> Alarm {
    let id = UUID()
    let alert = AlarmPresentation.Alert(
        title: "Good Morning",
        secondaryButton: AlarmButton(
            text: "Snooze 5 min", textColor: .white, systemImageName: "zzz"
        ),
        secondaryButtonBehavior: .countdown  // tapping Snooze restarts countdown
    )
    // postAlert defines the snooze duration
    let countdown = Alarm.CountdownDuration(
        preAlert: nil, postAlert: snoozeDurationSeconds
    )
    let countdownPresentation = AlarmPresentation.Countdown(
        title: "Snoozing...", pauseButton: nil
    )
    let presentation = AlarmPresentation(
        alert: alert, countdown: countdownPresentation
    )
    let attributes = AlarmAttributes(
        presentation: presentation,
        metadata: nil as WakeUpMetadata?,
        tintColor: .purple
    )
    let config = AlarmManager.AlarmConfiguration(
        countdownDuration: countdown,
        schedule: .relative(.init(
            time: .init(hour: hour, minute: minute), repeats: .never
        )),
        attributes: attributes,
        stopIntent: StopAlarmIntent(alarmID: id.uuidString),
        secondaryIntent: SnoozeAlarmIntent(alarmID: id.uuidString),
        sound: .default
    )
    return try await AlarmManager.shared.schedule(id: id, configuration: config)
}

Custom secondary action (open app)

Use .custom behavior to trigger the secondaryIntent instead of restarting a countdown. The intent opens the app or performs custom logic.

struct OpenAppIntent: LiveActivityIntent {
    static var title: LocalizedStringResource = "Open App"
    func perform() async throws -> some IntentResult { .result() }
}

func scheduleAlarmWithOpenAction(hour: Int, minute: Int) async throws -> Alarm {
    let id = UUID()
    let alert = AlarmPresentation.Alert(
        title: "Medication Reminder",
        secondaryButton: AlarmButton(
            text: "Open", textColor: .blue, systemImageName: "pill.fill"
        ),
        secondaryButtonBehavior: .custom  // triggers secondaryIntent
    )
    let presentation = AlarmPresentation(alert: alert)
    let attributes = AlarmAttributes<WakeUpMetadata>(
        presentation: presentation, metadata: nil, tintColor: .blue
    )
    let config = AlarmManager.AlarmConfiguration.alarm(
        schedule: .relative(.init(
            time: .init(hour: hour, minute: minute), repeats: .never
        )),
        attributes: attributes,
        stopIntent: StopAlarmIntent(alarmID: id.uuidString),
        secondaryIntent: OpenAppIntent(),
        sound: .default
    )
    return try await AlarmManager.shared.schedule(id: id, configuration: config)
}

Info.plist Configuration

Required key

<key>NSAlarmKitUsageDescription</key>
<string>We schedule alerts for alarms and timers you create.</string>

This key is mandatory. If missing or empty, schedule(id:configuration:) will fail and no alarms can be created by the app.

Recommended: NSSupportsLiveActivities

Since alarms create Live Activities, also include:

<key>NSSupportsLiveActivities</key>
<true/>

Error Handling

import AlarmKit

func scheduleAlarmSafely(
    id: UUID,
    configuration: AlarmManager.AlarmConfiguration<some AlarmMetadata>
) async {
    guard AlarmManager.shared.authorizationState == .authorized else {
        print("Not authorized -- request authorization first")
        return
    }
    do {
        let alarm = try await AlarmManager.shared.schedule(
            id: id, configuration: configuration
        )
        print("Scheduled alarm: \(alarm.id), state: \(alarm.state)")
    } catch let error as AlarmManager.AlarmError {
        switch error {
        case .maximumLimitReached:
            print("Too many alarms -- cancel an existing one first")
        @unknown default:
            print("AlarmKit error: \(error)")
        }
    } catch {
        print("Unexpected error: \(error)")
    }
}

// State transition helpers -- each throws if alarm is in wrong state
func cancelAlarmSafely(id: Alarm.ID) {
    do { try AlarmManager.shared.cancel(id: id) }
    catch { print("Failed to cancel: \(error)") }
}

func pauseAlarmSafely(id: Alarm.ID) {
    // Only valid when alarm is in .countdown state
    do { try AlarmManager.shared.pause(id: id) }
    catch { print("Cannot pause: \(error)") }
}

Apple Documentation Links

• AlarmKit
• AlarmManager
• AlarmAttributes
• AlarmPresentation
• AlarmPresentationState
• AlarmButton
• Alarm
• Alarm.Schedule
• Alarm.CountdownDuration
• Scheduling an alarm with AlarmKit