Alarmkit

AlarmKit

Framework for scheduling alarms and countdown timers with custom UI, Live Activities integration, and focus/silent mode override. Prevents the most common mistakes: using the wrong authorization property name, omitting the Info.plist key, and forgetting the widget extension for countdown presentations.

When This Skill Activates

Use this skill when the user:

• Asks to add, fix, or review alarm or timer functionality
• Mentions AlarmKit, AlarmManager, or AlarmPresentation
• Wants to schedule one-time, repeating, or countdown alarms
• Asks about snooze, stop, or repeat buttons on alarm alerts
• Wants alarms to appear on Dynamic Island or Lock Screen (Live Activities)
• Mentions overriding Focus or silent mode for alarms
• Asks about AlarmAttributes or AlarmMetadata

Decision Tree

Choose the right reference file based on what the user needs:

What do you need?
|
+-- Schedule an alarm (one-time, repeating, or timer)
|   --> scheduling.md
|       +-- One-time alarm: Alarm.Schedule.relative + .repeats: .never
|       +-- Repeating alarm: Alarm.Schedule.relative + .repeats: .weekly(weekdays)
|       +-- Countdown timer: CountdownDuration (no schedule)
|       +-- Authorization & Info.plist setup
|       +-- Managing alarms: pause, resume, cancel
|
+-- Customize alarm UI (alert, countdown, paused screens)
|   --> presentation.md
|       +-- AlarmPresentation.Alert: title, stop, snooze/repeat buttons
|       +-- AlarmPresentation.Countdown: title, pause button
|       +-- AlarmPresentation.Paused: title, resume button
|       +-- Custom buttons with AlarmButton
|       +-- Tint color and metadata via AlarmAttributes
|
+-- Show alarm on Dynamic Island / Lock Screen
    --> live-activities.md
        +-- Widget extension with ActivityConfiguration
        +-- AlarmAttributes conformance
        +-- Custom AlarmMetadata protocol

API Availability

Top Mistakes -- Quick Reference

Review Checklist

When reviewing AlarmKit code, verify:

• [ ] Info.plist -- NSAlarmKitUsageDescription is present with a meaningful description
• [ ] Authorization -- requestAuthorization() is called before scheduling; denial is handled gracefully
• [ ] Correct property -- uses .authorizationState, not .authorizationStatus
• [ ] Alarm ID persistence -- alarm UUIDs are stored (e.g., UserDefaults, SwiftData) for later management
• [ ] State observation -- alarmUpdates async sequence is used to keep UI in sync
• [ ] Widget extension -- exists if countdown or paused presentations are used
• [ ] Error handling -- schedule(), pause(), resume(), cancel() calls handle errors
• [ ] System limits -- code accounts for the system limit on number of active alarms
• [ ] Real device testing -- alarms are tested on physical devices, not just Simulator

Reference Files

Live Activities Integration

Displaying alarms and countdown timers on the Dynamic Island and Lock Screen using a widget extension.

Why You Need a Widget Extension

AlarmKit countdown and paused presentations appear on the Lock Screen and Dynamic Island through Live Activities. To render custom UI for these states, you must implement a widget extension with an ActivityConfiguration for AlarmAttributes.

Without the widget extension, the system cannot display countdown or paused presentations. Alert presentations work without a widget extension, but the countdown and paused states will not appear.

Setting Up the Widget Extension

1. Add a Widget Extension Target

In Xcode, add a new target: File > New > Target > Widget Extension. This creates a widget bundle where you add the alarm activity configuration.

2. Implement ActivityConfiguration

import WidgetKit
import SwiftUI
import AlarmKit

struct AlarmActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: AlarmAttributes.self) { context in
            // Lock Screen presentation
            AlarmLockScreenView(context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                // Expanded region
                DynamicIslandExpandedRegion(.center) {
                    Text(context.attributes.presentation.title)
                        .font(.headline)
                }
                DynamicIslandExpandedRegion(.bottom) {
                    // Show countdown or paused state
                    AlarmExpandedView(context: context)
                }
            } compactLeading: {
                Image(systemName: "alarm.fill")
            } compactTrailing: {
                Text("Timer")
                    .font(.caption)
            } minimal: {
                Image(systemName: "alarm.fill")
            }
        }
    }
}

3. Register in Widget Bundle

@main
struct MyAppWidgets: WidgetBundle {
    var body: some Widget {
        // Your other widgets...
        AlarmActivityWidget()
    }
}

AlarmAttributes

AlarmAttributes is the type that conforms to ActivityAttributes and carries all the information needed to render alarm UI in Live Activities. AlarmKit provides this type -- you do not define it yourself.

Key properties available in the activity context:

• Presentation information (title, buttons)
• Metadata (if you conform to AlarmMetadata)
• Tint color

Custom AlarmMetadata

To pass app-specific data to your widget extension, conform a type to the AlarmMetadata protocol. This allows you to include custom information that your Live Activity views can use.

import AlarmKit

struct MyAlarmMetadata: AlarmMetadata {
    let category: String
    let iconName: String
    let note: String
}

Use it when scheduling:

try await AlarmManager.shared.schedule(id: alarmID) {
    CountdownDuration(preAlert: 600, postAlert: 30)

    AlarmPresentation.Countdown(
        title: "Workout",
        pauseButton: AlarmButton(label: "Pause")
    )

    AlarmPresentation.Alert(
        title: "Workout Complete!",
        stopButton: AlarmButton(label: "Done")
    )

    AlarmPresentation.Paused(
        title: "Workout Paused",
        resumeButton: AlarmButton(label: "Resume")
    )

    MyAlarmMetadata(
        category: "fitness",
        iconName: "figure.run",
        note: "30-minute HIIT session"
    )

    AlarmAttributes(tintColor: .orange)
}

Lock Screen View Example

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

    var body: some View {
        HStack {
            Image(systemName: "alarm.fill")
                .foregroundStyle(context.attributes.tintColor ?? .primary)

            VStack(alignment: .leading) {
                Text(context.attributes.presentation.title)
                    .font(.headline)
            }

            Spacer()
        }
        .padding()
    }
}

Common Patterns

Minimal Setup for Timer Apps

If you only need basic countdown display, the widget extension can be straightforward:

struct AlarmActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: AlarmAttributes.self) { context in
            // Lock Screen -- simple layout
            HStack {
                Image(systemName: "timer")
                Text(context.attributes.presentation.title)
                    .font(.headline)
                Spacer()
            }
            .padding()
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.center) {
                    Text(context.attributes.presentation.title)
                }
            } compactLeading: {
                Image(systemName: "timer")
            } compactTrailing: {
                Text(context.attributes.presentation.title)
                    .font(.caption)
            } minimal: {
                Image(systemName: "timer")
            }
        }
    }
}

Anti-Patterns

// ❌ WRONG: Defining your own AlarmAttributes type
// AlarmKit provides AlarmAttributes -- do not create a custom struct with the same name
struct AlarmAttributes: ActivityAttributes {
    // ...
}
// ✅ Import AlarmKit and use the framework-provided AlarmAttributes

// ❌ WRONG: Using countdown presentations without a widget extension
// The countdown/paused UI simply will not appear
// ✅ Always add a widget extension with ActivityConfiguration(for: AlarmAttributes.self)

Checklist for Live Activities

• [ ] Widget extension target added to the Xcode project
• [ ] ActivityConfiguration(for: AlarmAttributes.self) implemented
• [ ] Widget registered in the WidgetBundle
• [ ] Lock Screen layout tested on real device
• [ ] Dynamic Island compact, expanded, and minimal views implemented
• [ ] Tint color applied via AlarmAttributes(tintColor:) if desired
• [ ] Custom AlarmMetadata conformance if passing app-specific data

Alarm Presentation

Customizing the alarm UI for alert, countdown, and paused states. Includes button configuration, tint color, and AlarmAttributes.

Presentation States

AlarmKit defines three presentation states. Each state has its own UI configuration type.

AlarmPresentation.Alert

The alert state is shown when an alarm fires. It always has a title and a stop button, with an optional secondary button.

Basic Alert

AlarmPresentation.Alert(
    title: "Wake Up!",
    stopButton: AlarmButton(label: "Stop")
)

Alert with Snooze

AlarmPresentation.Alert(
    title: "Morning Alarm",
    stopButton: AlarmButton(label: "Stop"),
    secondaryButton: .snoozeButton()
)

Alert with Open App Button

AlarmPresentation.Alert(
    title: "Meditation Time",
    stopButton: AlarmButton(label: "Dismiss"),
    secondaryButton: .openAppButton()
)

Alert with Repeat Button

Useful for timers that the user may want to restart immediately.

AlarmPresentation.Alert(
    title: "Time's Up!",
    stopButton: AlarmButton(label: "Done"),
    secondaryButton: .repeatButton()
)

Secondary Button Types

Secondary Button Behavior

The secondaryButtonBehavior parameter controls what happens visually when the secondary button is tapped:

AlarmPresentation.Alert(
    title: "Cooking Timer",
    stopButton: AlarmButton(label: "Stop"),
    secondaryButton: .snoozeButton(),
    secondaryButtonBehavior: .countdown  // Shows a countdown after snooze
)

Custom Buttons

Create buttons with custom labels using AlarmButton:

AlarmPresentation.Alert(
    title: "Study Break",
    stopButton: AlarmButton(label: "End Session"),
    secondaryButton: .snoozeButton()
)

AlarmPresentation.Countdown

Shown while a timer is actively counting down. Requires a widget extension to render on the Lock Screen and Dynamic Island.

AlarmPresentation.Countdown(
    title: "Cooking Timer",
    pauseButton: AlarmButton(label: "Pause")
)

The countdown UI displays the remaining time automatically. You only configure the title and pause button.

AlarmPresentation.Paused

Shown when a countdown timer has been paused by the user.

AlarmPresentation.Paused(
    title: "Timer Paused",
    resumeButton: AlarmButton(label: "Resume")
)

AlarmAttributes

AlarmAttributes bundles all presentation information together. It includes the presentations, optional metadata, and a tint color.

Tint Color

Apply a tint color to the alarm UI:

try await AlarmManager.shared.schedule(id: alarmID) {
    // ... schedule and presentations ...

    AlarmAttributes(tintColor: .blue)
}

Complete Configuration Example

A fully configured timer with all three presentation states and a tint color:

func scheduleFullTimer() async throws -> Alarm {
    let alarmID = UUID()

    let alarm = try await AlarmManager.shared.schedule(id: alarmID) {
        CountdownDuration(preAlert: 1800, postAlert: 120)

        AlarmPresentation.Countdown(
            title: "Focus Session",
            pauseButton: AlarmButton(label: "Pause")
        )

        AlarmPresentation.Alert(
            title: "Focus Session Complete",
            stopButton: AlarmButton(label: "Done"),
            secondaryButton: .repeatButton(),
            secondaryButtonBehavior: .countdown
        )

        AlarmPresentation.Paused(
            title: "Session Paused",
            resumeButton: AlarmButton(label: "Resume")
        )

        AlarmAttributes(tintColor: .purple)
    }

    return alarm
}

Common Patterns

Alarm-Only (No Timer)

For a simple alarm with no countdown phase, you only need the alert presentation:

try await AlarmManager.shared.schedule(id: UUID()) {
    Alarm.Schedule.relative(.repeats: .never)

    AlarmPresentation.Alert(
        title: "Reminder",
        stopButton: AlarmButton(label: "OK")
    )
}

Timer with All States

For a countdown timer, provide all three presentations so the user has a complete experience:

try await AlarmManager.shared.schedule(id: UUID()) {
    CountdownDuration(preAlert: 600, postAlert: 30)

    AlarmPresentation.Countdown(
        title: "Egg Timer",
        pauseButton: AlarmButton(label: "Pause")
    )

    AlarmPresentation.Alert(
        title: "Eggs are Ready!",
        stopButton: AlarmButton(label: "Done"),
        secondaryButton: .repeatButton()
    )

    AlarmPresentation.Paused(
        title: "Egg Timer Paused",
        resumeButton: AlarmButton(label: "Resume")
    )
}

Anti-Patterns

// ❌ WRONG: Countdown presentation without a widget extension
// The countdown UI will not appear on Lock Screen or Dynamic Island
// without implementing ActivityConfiguration(for: AlarmAttributes.self)
AlarmPresentation.Countdown(title: "Timer", pauseButton: AlarmButton(label: "Pause"))
// ✅ Implement the widget extension -- see live-activities.md

// ❌ WRONG: Alert without a stop button
// AlarmPresentation.Alert always requires a stopButton
AlarmPresentation.Alert(title: "Alarm")
// ✅ Always provide a stopButton
AlarmPresentation.Alert(title: "Alarm", stopButton: AlarmButton(label: "Stop"))

Scheduling Alarms and Timers

Authorization setup, creating one-time/repeating alarms and countdown timers, managing alarm lifecycle, and observing state changes.

Authorization

Info.plist Requirement

You must add NSAlarmKitUsageDescription to your app's Info.plist before requesting authorization. Without it, the authorization request will fail silently.

<key>NSAlarmKitUsageDescription</key>
<string>This app needs alarm access to wake you up at your scheduled times.</string>

Requesting Authorization

import AlarmKit

func requestAlarmAccess() async {
    let state = await AlarmManager.shared.requestAuthorization()

    switch state {
    case .authorized:
        // Can schedule alarms
        break
    case .denied:
        // Show settings prompt to the user
        break
    case .notDetermined:
        // Should not happen after request, but handle gracefully
        break
    @unknown default:
        break
    }
}

Checking Current Authorization

// ✅ Correct property name
let state = AlarmManager.shared.authorizationState

// ❌ WRONG: This property does NOT exist
let state = AlarmManager.shared.authorizationStatus

Observing Authorization Changes

func observeAuthorizationChanges() async {
    for await state in AlarmManager.shared.authorizationUpdates {
        switch state {
        case .authorized:
            // Update UI to show alarm features
            break
        case .denied:
            // Hide alarm features, show explanation
            break
        default:
            break
        }
    }
}

Creating Alarms

All alarms are created through AlarmManager.shared.schedule(id:configuration:).

One-Time Alarm

A single alarm that fires once and does not repeat.

import AlarmKit

func scheduleOneTimeAlarm() async throws -> Alarm {
    let alarmID = UUID()

    let alarm = try await AlarmManager.shared.schedule(id: alarmID) {
        Alarm.Schedule.relative(
            .repeats: .never
        )

        AlarmPresentation.Alert(
            title: "Wake Up!",
            stopButton: AlarmButton(label: "Stop"),
            secondaryButton: .snoozeButton()
        )
    }

    // Persist the alarm ID for later management
    UserDefaults.standard.set(alarmID.uuidString, forKey: "morningAlarmID")

    return alarm
}

Repeating Alarm

An alarm that fires on specific days of the week.

func scheduleWeekdayAlarm() async throws -> Alarm {
    let alarmID = UUID()

    let alarm = try await AlarmManager.shared.schedule(id: alarmID) {
        Alarm.Schedule.relative(
            .repeats: .weekly([.monday, .tuesday, .wednesday, .thursday, .friday])
        )

        AlarmPresentation.Alert(
            title: "Time for Work",
            stopButton: AlarmButton(label: "Dismiss"),
            secondaryButton: .snoozeButton()
        )
    }

    return alarm
}

Countdown Timer

Timers use CountdownDuration and do not include a schedule. The preAlert parameter is the countdown duration in seconds before the alert fires. The postAlert parameter defines an optional snooze duration.

// ✅ Timer with countdown -- no schedule
func startTimer(minutes: Int) async throws -> Alarm {
    let alarmID = UUID()

    let alarm = try await AlarmManager.shared.schedule(id: alarmID) {
        CountdownDuration(
            preAlert: TimeInterval(minutes * 60),
            postAlert: 60  // 60-second snooze after alert
        )

        AlarmPresentation.Countdown(
            title: "Timer",
            pauseButton: AlarmButton(label: "Pause")
        )

        AlarmPresentation.Alert(
            title: "Time's Up!",
            stopButton: AlarmButton(label: "Done"),
            secondaryButton: .repeatButton()
        )

        AlarmPresentation.Paused(
            title: "Timer Paused",
            resumeButton: AlarmButton(label: "Resume")
        )
    }

    return alarm
}

// ❌ WRONG: Do not pass a schedule with a timer
func wrongTimer() async throws -> Alarm {
    let alarmID = UUID()
    return try await AlarmManager.shared.schedule(id: alarmID) {
        Alarm.Schedule.relative(.repeats: .never)  // Wrong -- timers don't use schedules
        CountdownDuration(preAlert: 300, postAlert: 60)
        // ...
    }
}

Managing Alarms

Listing Active Alarms

let activeAlarms = AlarmManager.shared.alarms
for alarm in activeAlarms {
    print("Alarm \(alarm.id)")
}

Pause, Resume, and Cancel

let alarmID: UUID = // ... retrieved from persistence

// Pause a countdown timer
try await AlarmManager.shared.pause(id: alarmID)

// Resume a paused timer
try await AlarmManager.shared.resume(id: alarmID)

// Cancel an alarm entirely
try await AlarmManager.shared.cancel(id: alarmID)

Observing Alarm Updates

Use the alarmUpdates async sequence to keep your app's state synchronized with the system. This is the recommended way to track alarm state changes rather than polling.

func observeAlarms() async {
    for await alarms in AlarmManager.shared.alarmUpdates {
        // alarms is the updated [Alarm] array
        await MainActor.run {
            self.activeAlarms = alarms
        }
    }
}

Persisting Alarm IDs

AlarmKit does not provide a way to look up alarms by custom identifiers. You must store the UUID returned from scheduling so you can pause, resume, or cancel alarms later.

// ✅ Persist alarm IDs
struct AlarmStore {
    private let defaults = UserDefaults.standard
    private let key = "scheduledAlarmIDs"

    func save(alarmID: UUID, label: String) {
        var stored = defaults.dictionary(forKey: key) as? [String: String] ?? [:]
        stored[alarmID.uuidString] = label
        defaults.set(stored, forKey: key)
    }

    func alarmID(for label: String) -> UUID? {
        let stored = defaults.dictionary(forKey: key) as? [String: String] ?? [:]
        return stored.first(where: { $0.value == label }).map { UUID(uuidString: $0.key)! }
    }

    func remove(alarmID: UUID) {
        var stored = defaults.dictionary(forKey: key) as? [String: String] ?? [:]
        stored.removeValue(forKey: alarmID.uuidString)
        defaults.set(stored, forKey: key)
    }
}

Error Handling

Always wrap scheduling and management calls in do/catch blocks. The system imposes a limit on the number of active alarms, and calls can fail for various reasons (authorization denied, system limit reached, invalid configuration).

do {
    let alarm = try await AlarmManager.shared.schedule(id: UUID()) {
        // ... configuration
    }
} catch {
    // Handle error -- could be authorization, system limit, or invalid config
    print("Failed to schedule alarm: \(error.localizedDescription)")
}

Common Patterns

Alarm Manager View Model

import AlarmKit
import SwiftUI

@Observable
final class AlarmViewModel {
    private(set) var alarms: [Alarm] = []
    private(set) var isAuthorized = false

    func setup() async {
        let state = await AlarmManager.shared.requestAuthorization()
        isAuthorized = (state == .authorized)

        // Start observing in a detached task
        Task {
            await observeAlarms()
        }
    }

    private func observeAlarms() async {
        for await updatedAlarms in AlarmManager.shared.alarmUpdates {
            await MainActor.run {
                self.alarms = updatedAlarms
            }
        }
    }

    func cancelAlarm(id: UUID) async {
        do {
            try await AlarmManager.shared.cancel(id: id)
        } catch {
            print("Cancel failed: \(error)")
        }
    }
}