axiom-alarmkit-ref

name	axiom-alarmkit-ref
description	Use when implementing alarm functionality, scheduling wake alarms, or integrating AlarmKit with Live Activities. Covers AlarmKit authorization, alarm configuration, SwiftUI views, and Live Activity integration.
license	MIT

AlarmKit Reference

Complete API reference for AlarmKit, Apple's framework for scheduling alarms and countdown timers with system-level alerting, Dynamic Island integration, and focus/silent mode override.

Overview

AlarmKit lets apps create alarms and timers that behave like the built-in Clock app -- they override Do Not Disturb, appear in the Dynamic Island, and show on the Lock Screen. The framework handles scheduling, snooze, pause/resume, and UI presentation through a small set of types centered on AlarmManager.

System Requirements

• iOS 26+ (AlarmKit introduced in iOS 26)
• Widget Extension required for Live Activity / Dynamic Island presentation
• Physical device recommended for alarm sound and notification testing

---

Part 1: Key Components

AlarmManager

Singleton entry point for all alarm operations.

import AlarmKit

let manager = AlarmManager.shared

All scheduling, cancellation, and observation flows through this shared instance.

Alarm

Describes an alarm that can alert once or on a repeating schedule.

struct Alarm {
    var id: UUID
    var schedule: Schedule?
    var countdownDuration: CountdownDuration?
    var state: AlarmState
}

AlarmPresentation

Content for the alarm UI across three states -- alerting, counting down, and paused.

struct AlarmPresentation {
    var alert: Alert           // Required: shown when alarm fires
    var countdown: Countdown?  // Optional: shown during countdown
    var paused: Paused?        // Optional: shown when paused
}

AlarmAttributes

Generic container pairing presentation with app-specific metadata and tint color. Used to configure the Live Activity widget.

struct AlarmAttributes<Metadata: AlarmMetadata> {
    var presentation: AlarmPresentation
    var metadata: Metadata
    var tintColor: Color
}

AlarmMetadata

Protocol for app-specific data attached to an alarm. Conform an empty struct for minimal usage, or add properties for richer UI.

struct RecipeMetadata: AlarmMetadata {
    let recipeName: String
    let cookingStep: String
}

---

Part 2: Authorization

Apps must request permission before scheduling alarms. Add NSAlarmKitUsageDescription to Info.plist.

Requesting Authorization

func requestAlarmAuthorization() async -> Bool {
    do {
        let state = try await AlarmManager.shared.requestAuthorization()
        return state == .authorized
    } catch {
        print("Authorization error: \(error)")
        return false
    }
}

Checking Current State

Use authorizationState (not authorizationStatus) to read the current value:

let state = await AlarmManager.shared.authorizationState
// .authorized | .denied | .notDetermined

Observing Authorization Changes

for await authState in AlarmManager.shared.authorizationUpdates {
    switch authState {
    case .authorized: enableAlarmUI()
    case .denied:     showPermissionPrompt()
    case .notDetermined: break
    @unknown default: break
    }
}

---

Part 3: Scheduling Alarms

Every alarm requires a UUID, an AlarmManager.AlarmConfiguration, and a call to schedule(id:configuration:).

One-Time Alarm

let id = UUID()
let time = Alarm.Schedule.Relative.Time(hour: 7, minute: 30)
let schedule = Alarm.Schedule.relative(.init(
    time: time,
    repeats: .never
))

let alert = AlarmPresentation.Alert(
    title: "Wake Up",
    stopButton: .stopButton,
    secondaryButton: .snoozeButton,
    secondaryButtonBehavior: .countdown
)

struct EmptyMetadata: AlarmMetadata {}
let config = AlarmManager.AlarmConfiguration(
    countdownDuration: nil,
    schedule: schedule,
    attributes: AlarmAttributes(
        presentation: AlarmPresentation(alert: alert),
        metadata: EmptyMetadata(),
        tintColor: .blue
    ),
    sound: .default
)

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

Repeating Alarm

Use .weekly(Array(weekdays)) for specific days:

let time = Alarm.Schedule.Relative.Time(hour: 6, minute: 0)
let schedule = Alarm.Schedule.relative(.init(
    time: time,
    repeats: .weekly([.monday, .tuesday, .wednesday, .thursday, .friday])
))

Countdown Timer

Set schedule: nil and provide countdownDuration with a preAlert interval:

let countdown = Alarm.CountdownDuration(
    preAlert: 300,  // 5 minutes
    postAlert: 10   // Optional post-alert snooze window
)

let config = AlarmManager.AlarmConfiguration(
    countdownDuration: countdown,
    schedule: nil,
    attributes: attributes,
    sound: .default
)

Timers support pause/resume and show a countdown presentation when AlarmPresentation.countdown is provided.

Snooze Configuration

Snooze uses CountdownDuration.postAlert combined with a .snoozeButton secondary action:

let alert = AlarmPresentation.Alert(
    title: "Alarm",
    stopButton: .stopButton,
    secondaryButton: .snoozeButton,
    secondaryButtonBehavior: .countdown  // Starts post-alert countdown
)

let countdownDuration = Alarm.CountdownDuration(
    preAlert: nil,
    postAlert: 9 * 60  // 9-minute snooze
)

---

Part 4: Customizing Alarm UI

Alert Presentation

The alert state is shown when the alarm fires. The stop button is required; secondary button is optional.

// Minimal
let basic = AlarmPresentation.Alert(
    title: "Alarm",
    stopButton: .stopButton
)

// With custom button labels
let custom = AlarmPresentation.Alert(
    title: "Medication Reminder",
    stopButton: AlarmButton(label: "Taken"),
    secondaryButton: AlarmButton(label: "Remind Later"),
    secondaryButtonBehavior: .countdown
)

// With open-app action
let openApp = AlarmPresentation.Alert(
    title: "Workout Time",
    stopButton: .stopButton,
    secondaryButton: .openAppButton,
    secondaryButtonBehavior: .custom
)

Countdown Presentation

Shown while a timer counts down. Only relevant for alarms with countdownDuration.preAlert.

let countdown = AlarmPresentation.Countdown(
    title: "Timer Running",
    pauseButton: .pauseButton
)

Paused Presentation

Shown when a countdown timer is paused.

let paused = AlarmPresentation.Paused(
    title: "Timer Paused",
    resumeButton: .resumeButton
)

Full Three-State Presentation

Combine all three for a complete timer experience:

let presentation = AlarmPresentation(
    alert: AlarmPresentation.Alert(
        title: "Timer Complete",
        stopButton: .stopButton,
        secondaryButton: .repeatButton,
        secondaryButtonBehavior: .countdown
    ),
    countdown: AlarmPresentation.Countdown(
        title: "Cooking Timer",
        pauseButton: .pauseButton
    ),
    paused: AlarmPresentation.Paused(
        title: "Timer Paused",
        resumeButton: .resumeButton
    )
)

---

Part 5: Managing Alarms

Retrieve All Alarms

let alarms = try AlarmManager.shared.alarms

Pause / Resume

try await AlarmManager.shared.pause(id: alarmID)
try await AlarmManager.shared.resume(id: alarmID)

Cancel

try await AlarmManager.shared.cancel(id: alarmID)

Observe Alarm Updates

Use alarmUpdates to keep UI in sync. An alarm absent from the emitted array is no longer scheduled.

for await alarms in AlarmManager.shared.alarmUpdates {
    self.alarms = alarms
}

---

Part 6: Live Activity Integration

AlarmKit alarms appear in the Dynamic Island and Lock Screen through ActivityConfiguration. Add a Widget Extension target and implement the widget using AlarmAttributes.

struct AlarmWidgetView: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: AlarmAttributes<YourMetadata>.self) { context in
            // Lock Screen presentation
            VStack {
                Text(context.attributes.presentation.alert.title)
                if context.state.mode == .countdown {
                    Text(
                        timerInterval: context.state.countdownEndDate
                            .timeIntervalSinceNow,
                        countsDown: true
                    )
                    .bold()
                }
            }
            .padding()
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) {
                    Text(context.attributes.presentation.alert.title)
                }
                DynamicIslandExpandedRegion(.trailing) {
                    if context.state.mode == .countdown {
                        Text(
                            timerInterval: context.state.countdownEndDate
                                .timeIntervalSinceNow,
                            countsDown: true
                        )
                    }
                }
            } compactLeading: {
                Image(systemName: "alarm")
            } compactTrailing: {
                if context.state.mode == .countdown {
                    Text(
                        timerInterval: context.state.countdownEndDate
                            .timeIntervalSinceNow,
                        countsDown: true
                    )
                }
            } minimal: {
                (systemName: )
            }
        }
    }
}

---

Part 7: SwiftUI Integration

ViewModel Pattern with @Observable

import AlarmKit

@Observable
class AlarmViewModel {
    var alarms: [Alarm] = []
    private let manager = AlarmManager.shared

    func requestAuthorization() {
        Task {
            _ = try? await manager.requestAuthorization()
        }
    }

    func loadAndObserve() {
        Task {
            alarms = (try? manager.alarms) ?? []
            for await updated in manager.alarmUpdates {
                alarms = updated
            }
        }
    }

    func addAlarm(hour: Int, minute: Int, weekdays: Set<Locale.Weekday>) {
        Task {
            let time = Alarm.Schedule.Relative.Time(hour: hour, minute: minute)
            let schedule = Alarm.Schedule.relative(.init(
                time: time,
                repeats: weekdays.isEmpty ? .never : .weekly((weekdays))
            ))

             alert  .(
                title: ,
                stopButton: .stopButton,
                secondaryButton: .snoozeButton,
                secondaryButtonBehavior: .countdown
            )

             :  {}
             config  .(
                countdownDuration: .(
                    preAlert: , postAlert:   
                ),
                schedule: schedule,
                attributes: (
                    presentation: (alert: alert),
                    metadata: (),
                    tintColor: .blue
                ),
                sound: .default
            )

                manager.schedule(id: (), configuration: config)
        }
    }

     (: ) {
         {   manager.cancel(id: id) }
    }

     (: , : ) {
         {
             isPaused {
                  manager.resume(id: id)
            }  {
                  manager.pause(id: id)
            }
        }
    }
}

Alarm List View

struct AlarmListView: View {
    @State private var viewModel = AlarmViewModel()

    var body: some View {
        NavigationStack {
            List(viewModel.alarms, id: \.id) { alarm in
                AlarmRow(alarm: alarm, viewModel: viewModel)
            }
            .navigationTitle("Alarms")
            .onAppear {
                viewModel.requestAuthorization()
                viewModel.loadAndObserve()
            }
        }
    }
}

---

Part 8: Best Practices

Practice	Detail
Request authorization early	On first launch or first alarm creation attempt
Handle denial gracefully	Guide users to Settings if permission was denied
Persist alarm UUIDs	Store IDs to manage alarms across app launches
Implement widget extension	Required for countdown/Dynamic Island presentation
Use alarmUpdates	Keep UI in sync; don't poll or cache stale state
Test on physical device	Alarm sounds, notifications, and Live Activities require real hardware
Respect system limits	There is a system-imposed cap on alarms per app
Use authorizationState	Not authorizationStatus -- the correct property name is authorizationState

---

Resources

WWDC: 2025-230

Docs: /alarmkit, /alarmkit/alarmmanager, /alarmkit/alarm, /alarmkit/alarmpresentation, /alarmkit/alarmattributes

Skills: axiom-extensions-widgets-ref, axiom-swiftui-26-ref