---
name: alarmkit
description: "AlarmKit alarms and countdown timers on iOS and iPadOS 26: AlarmManager scheduling and authorization, AlarmAttributes, AlarmPresentation, AlarmButton stop and snooze, state observation, and the widget extension for countdown Live Activity UI on the Lock Screen, Dynamic Island, StandBy and paired Apple Watch. Use when an app needs wake-up alarms, countdown timers or any alert that needs the system alarm experience. Not for plain widgets or non-alarm Live Activities."
metadata:
  source: multi-agent-pipeline
---

# AlarmKit

AlarmKit lets an app hand an alarm or a countdown timer to the system. When it
fires, the alert shows up on the Lock Screen, in the Dynamic Island, in StandBy
and on the Apple Watch paired with the phone, and it can sound through Focus
and the Silent switch. The framework is available on iOS 26 and iPadOS 26 and later.

Under the hood an alarm is a Live Activity built on ActivityKit types, but the
firing alert itself is drawn by the system and cannot be restyled. The only
custom UI an app provides is for the countdown and paused states, and that UI
lives in a widget extension that uses the same `AlarmAttributes<Metadata>` and
`AlarmPresentationState` the app used when scheduling.

```swift
import AlarmKit
```

Availability note: the `AlarmPresentation.Alert(title:secondaryButton:secondaryButtonBehavior:)`
initializer used throughout this skill is iOS 26.1+. On a 26.0 deployment target,
gate it with `if #available(iOS 26.1, *)`; the older initializer with a
`stopButton:` argument is deprecated from 26.1 and should only appear in that
fallback branch.

## Workflows

### Adding an alarm or timer

1. Put `NSAlarmKitUsageDescription` in the app's Info.plist with a sentence the
   user will understand.
2. Ask for permission with `AlarmManager.shared.requestAuthorization()` at a
   moment where the value is obvious, or let the system ask on the first
   `schedule` call.
3. If the state comes back `.denied` (or anything other than `.authorized`),
   show a recovery screen instead of scheduling.
4. Describe each state's text and buttons with `AlarmPresentation` (alert, plus
   countdown and paused if used).
5. Wrap that in `AlarmAttributes` with optional metadata and a tint color.
6. Build an `AlarmManager.AlarmConfiguration`, either an alarm or a timer.
7. Call `AlarmManager.shared.schedule(id:configuration:)`.
8. Watch `alarmUpdates` to keep the UI in sync.
9. If a countdown is shown, create a widget extension; its
   `ActivityConfiguration` must name the identical `AlarmAttributes<Metadata>` type.

### Reviewing existing alarm code

Go through the [Review checklist](#review-checklist) item by item.

## Authorization

The user must grant access. The app may ask up front, or AlarmKit will prompt
the first time something is scheduled. If neither prompt ends in approval, no
alarm is scheduled and nothing will ring.

```swift
import AlarmKit

func ensureAlarmAccess() async -> Bool {
    let center = AlarmManager.shared
    switch center.authorizationState {
    case .authorized:
        return true
    case .denied:
        return false
    case .notDetermined:
        let answer = try? await center.requestAuthorization()
        return answer == .authorized
    @unknown default:
        return false
    }
}

func watchAlarmAccess(onChange: @escaping (Bool) -> Void) async {
    for await state in AlarmManager.shared.authorizationUpdates {
        switch state {
        case .authorized: onChange(true)
        case .denied, .notDetermined: onChange(false)
        @unknown default: onChange(false)
        }
    }
}
```

`AlarmManager.AuthorizationState` has three cases: `.notDetermined`,
`.denied` and `.authorized`. `authorizationState` is a synchronous read;
`authorizationUpdates` is an async sequence of changes.

## Alarm or timer?

| | `.alarm` | `.timer` |
|---|---|---|
| Fires | at a clock time | when a duration has elapsed |
| Countdown UI | optional | always shown |
| Repeats | yes, on chosen weekdays | no, one-shot |
| Typical use | wake-up, daily reminder | steeping tea, rest between sets |

Rule of thumb: the user picked a time of day, use `.alarm(schedule:...)`; the
user picked "in N minutes", use `.timer(duration:...)`.

## Scheduling

### Alarm.Schedule

```swift
import AlarmKit

let oneOff = Alarm.Schedule.fixed(Date(timeIntervalSinceNow: 3_600))

let sixAM = Alarm.Schedule.Relative.Time(hour: 6, minute: 0)
let tomorrowAtSix = Alarm.Schedule.relative(.init(time: sixAM, repeats: .never))

let classDays: [Locale.Weekday] = [.monday, .tuesday, .wednesday, .thursday, .friday]
let schoolRun = Alarm.Schedule.relative(.init(time: sixAM, repeats: .weekly(classDays)))
```

- `.fixed(Date)` rings once at that exact instant.
- `.relative` with `repeats: .never` rings once at a wall-clock time in the
  device's current time zone.
- `.relative` with `repeats: .weekly([Locale.Weekday])` repeats on those days.

### Configuring and scheduling

```swift
import AlarmKit
import SwiftUI

struct ShiftInfo: AlarmMetadata {
    var shiftName: String
}

@available(iOS 26.1, *)
func scheduleShiftAlarm() async throws -> Alarm {
    let dawn = Alarm.Schedule.Relative.Time(hour: 5, minute: 30)
    let alert = AlarmPresentation.Alert(
        title: "Early shift",
        secondaryButton: AlarmButton(text: "Later", textColor: .white, systemImageName: "zzz"),
        secondaryButtonBehavior: .countdown
    )
    let attributes = AlarmAttributes(
        presentation: AlarmPresentation(alert: alert),
        metadata: ShiftInfo(shiftName: "Warehouse A"),
        tintColor: .teal
    )
    let config = AlarmManager.AlarmConfiguration(
        countdownDuration: Alarm.CountdownDuration(preAlert: nil, postAlert: 9 * 60),
        schedule: .relative(.init(time: dawn, repeats: .never)),
        attributes: attributes,
        sound: .default
    )
    let center = AlarmManager.shared
    return try await center.schedule(id: UUID(), configuration: config)
}
```

Here `postAlert` is what makes the secondary button a snooze: pressing it
starts a nine-minute countdown and then rings again.

`stopIntent` and `secondaryIntent` both default to `nil`, and that is usually
right:

- Leave `stopIntent` out when the system Stop is all you need. Pass one only
  when stopping must also clean up app state or trigger some side effect.
- Leave `secondaryIntent` out for a plain snooze or repeat, which is
  `secondaryButtonBehavior: .countdown` plus `CountdownDuration.postAlert`.
  Pass one only with `.custom` behavior or when the app must do its own work.

### Lifecycle and transitions

The normal path is scheduled, then countdown, then alerting. From countdown
`pause(id:)` leads to paused and `resume(id:)` leads back. From alerting,
`stop(id:)` ends it and `countdown(id:)` snoozes it. `cancel(id:)` works from
anywhere.

| Call | Valid in | Effect |
|---|---|---|
| `cancel(id:)` | any state | deletes the alarm entirely, repeating ones included |
| `pause(id:)` | `.countdown` | freezes the countdown; throws elsewhere |
| `resume(id:)` | `.paused` | continues the countdown; throws elsewhere |
| `stop(id:)` | alerting | a one-shot alarm is deleted; a repeating one moves on to its next occurrence |
| `countdown(id:)` | `.alerting` | restarts the post-alert countdown (snooze); throws elsewhere |

## Countdown timers

A timer rings once a duration has passed and always shows its countdown.

```swift
import AlarmKit
import SwiftUI

struct BrewInfo: AlarmMetadata {
    var blend: String
}

@available(iOS 26.1, *)
func startSteepTimer() async throws {
    let presentation = AlarmPresentation(
        alert: .init(title: "Tea is ready"),
        countdown: .init(title: "Steeping"),
        paused: .init(title: "Steeping paused",
                      resumeButton: AlarmButton(text: "Resume", textColor: .white, systemImageName: "play.fill"))
    )
    let attributes = AlarmAttributes(presentation: presentation,
                                     metadata: BrewInfo(blend: "Sencha"),
                                     tintColor: .green)
    let threeMinutes = AlarmManager.AlarmConfiguration.timer(duration: 180, attributes: attributes, sound: .default)
    let center = AlarmManager.shared
    _ = try await center.schedule(id: UUID(), configuration: threeMinutes)
}
```

### CountdownDuration

| Property | Meaning |
|---|---|
| `preAlert` | seconds counted down before the alert fires (the main countdown) |
| `postAlert` | seconds counted down after the alert when the user snoozes or repeats |

Both can be combined with a schedule. A 7:00 alarm with `preAlert: 900` shows a
fifteen-minute countdown starting at 6:45; `postAlert: 600` gives a ten-minute
snooze:

```swift
import AlarmKit

func napDurations<M: AlarmMetadata>(_ attrs: AlarmAttributes<M>) -> AlarmManager.AlarmConfiguration<M> {
    let seven = Alarm.Schedule.Relative.Time(hour: 7, minute: 0)
    return .init(countdownDuration: .init(preAlert: 900, postAlert: 600),
                 schedule: .relative(.init(time: seven)), attributes: attrs, sound: .default)
}
```

## Alarm states

`Alarm.state` says where an alarm is in its lifecycle:

| State | Meaning |
|---|---|
| `.scheduled` | waiting for its time |
| `.countdown` | counting down (a timer, or an alarm's pre-alert) |
| `.paused` | countdown frozen by the user or the app |
| `.alerting` | ringing, with the prominent system UI |

### Observing changes

Reading `AlarmManager.shared.alarms` can throw; it hands back whatever the
alarm daemon currently holds, so it needs `try` inside a throwing context or a `do/catch`.
Changes arrive through `alarmUpdates`:

```swift
import AlarmKit

func trackAlarms(render: ([Alarm]) -> Void) async throws {
    let center = AlarmManager.shared
    render(try center.alarms)
    for await batch in center.alarmUpdates {
        for item in batch {
            switch item.state {
            case .scheduled, .countdown, .paused, .alerting: break
            @unknown default: break
            }
        }
        render(batch)
    }
}
```

When an ID disappears from `alarmUpdates`, AlarmKit no longer has it scheduled.
The sequence does not say why. To tell a fired one-shot from a cancelled alarm
or a rescheduled one, compare against the IDs the app saved itself.

## AlarmAttributes and AlarmPresentation

`AlarmAttributes` conforms to `ActivityAttributes` and carries the static part
of that Live Activity. Its generic parameter is `Metadata: AlarmMetadata`, a
protocol that refines `Decodable`, `Encodable`, `Hashable` and `Sendable`.
Passing `metadata` is optional; leave it out and it is `nil`.

### AlarmPresentation

`AlarmPresentation` describes the text and buttons per state. The system draws
the alerting UI from it; the widget extension may draw countdown and paused.

| Type | State | Required |
|---|---|---|
| `AlarmPresentation.Alert(title:secondaryButton:secondaryButtonBehavior:)` | alerting | yes |
| `AlarmPresentation.Countdown(title:pauseButton:)` | counting down | no |
| `AlarmPresentation.Paused(title:resumeButton:)` | paused | no |

Combine them with `AlarmPresentation(alert:countdown:paused:)`:

```swift
import AlarmKit
import SwiftUI

@available(iOS 26.1, *)
func workoutPresentation() -> AlarmPresentation {
    let again = AlarmButton(text: "Again", textColor: .white, systemImageName: "repeat")
    let hold = AlarmButton(text: "Hold", textColor: .orange, systemImageName: "pause.fill")
    let go = AlarmButton(text: "Go", textColor: .orange, systemImageName: "play.fill")
    return AlarmPresentation(
        alert: .init(title: "Rest over", secondaryButton: again, secondaryButtonBehavior: .countdown),
        countdown: .init(title: "Resting", pauseButton: hold),
        paused: .init(title: "Rest on hold", resumeButton: go)
    )
}
```

### Metadata

```swift
import AlarmKit
import SwiftUI

struct PlantInfo: AlarmMetadata { var plantName: String; var litres: Double }
struct NoAlarmData: AlarmMetadata {}

@available(iOS 26.1, *)
func plantAttributes() -> (AlarmAttributes<PlantInfo>, AlarmAttributes<NoAlarmData>) {
    let look = AlarmPresentation(alert: .init(title: "Water the fern"))
    let withData = AlarmAttributes(presentation: look, metadata: PlantInfo(plantName: "Fern", litres: 0.5), tintColor: .mint)
    let plain = AlarmAttributes<NoAlarmData>(presentation: look, metadata: nil, tintColor: .mint)
    return (withData, plain)
}
```

When there is nothing to carry, declare an empty type that conforms to
`AlarmMetadata` and pass `metadata: nil`.

### AlarmPresentationState

`AlarmPresentationState` is the alarm Live Activity's `ContentState`, owned and
updated by the system. It pairs an `alarmID` with a `mode` value:

| Mode | When | Carries |
|---|---|---|
| `.alert(Alert)` | ringing | the scheduled `time` |
| `.countdown(Countdown)` | counting down | fire date and durations |
| `.paused(Paused)` | paused | elapsed and total durations |

The widget extension switches on `context.state.mode` to choose Lock Screen and
Dynamic Island content for the non-alerting modes.

## AlarmButton

`AlarmButton(text:textColor:systemImageName:)` sets a button's label, color and
SF Symbol, for example a red `"stop.fill"` look for dismissing and a
`"bell.slash"` look for snoozing:
`AlarmButton(text: "Snooze", textColor: .yellow, systemImageName: "bell.slash")`.

### Secondary button behavior

| Behavior | What happens |
|---|---|
| `.countdown` | starts a new countdown of `postAlert` seconds (snooze) |
| `.custom` | runs `secondaryIntent`, for example to open the app |

## Live Activity integration

A ringing alarm is a Live Activity that the system renders on the Lock Screen,
in the Dynamic Island, in StandBy and on a paired Apple Watch; the app has no
say over that screen. Countdown and paused are different: the app supplies a widget
extension whose `ActivityConfiguration` names the same
`AlarmAttributes<Metadata>` type used at scheduling.

- Plan on the extension whenever countdown presentation is used. The metadata
  type must be compiled into both the app and the extension, and it should stay
  small.
- Leave the extension out and an alarm can vanish early or never ring. The
  system only draws a fallback countdown in narrow cases, such as after a
  restart before the first unlock.

AlarmKit is responsible for: permission to schedule alarms, `AlarmManager` scheduling and state,
`AlarmAttributes`, `AlarmPresentation`, `AlarmPresentationState`, the sound,
and the system Stop, Repeat and Open App actions. It is not a general surface
for custom notification UI.

When describing where alarms appear, name Lock Screen, Dynamic Island, StandBy
and paired Apple Watch together. Smart Stack is not an AlarmKit surface.

Hand-offs:

- Widgets on the Home Screen or in Smart Stack, `WidgetFamily`, timelines,
  `WidgetCenter` reloads: `widgetkit`.
- Non-alarm Live Activities (`Activity.request`, `update`, `end`),
  push-to-start and per-activity update tokens, and remote `content-state`
  payloads: `live-activities`.
- APNs, `UNUserNotificationCenter`, notification categories and actions,
  custom notification UI: `push-notifications`, unless the code ends up
  calling `AlarmManager`.

Setup stays with what Apple documents: `NSAlarmKitUsageDescription` and
`AlarmManager` authorization. Do not require extra keys or a
`com.apple.developer.alarmkit` entitlement unless a current Apple source says so.

```swift
import ActivityKit
import AlarmKit
import SwiftUI
import WidgetKit

struct CoachInfo: AlarmMetadata {
    var drill: String
}

struct CoachAlarmWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: AlarmAttributes<CoachInfo>.self) { context in
            Text(context.attributes.metadata?.drill ?? "Timer")
                .padding()
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.center) {
                    let heading = context.attributes.presentation.alert.title
                    Text(heading)
                }
                DynamicIslandExpandedRegion(.bottom) {
                    if case .countdown(let run) = context.state.mode {
                        Text(timerInterval: Date.now...run.fireDate, countsDown: true)
                    }
                }
            } compactLeading: {
                Image(systemName: "alarm.fill")
            } compactTrailing: {
                Image(systemName: "alarm.fill")
            } minimal: {
                Image(systemName: "alarm.fill")
            }
        }
    }
}

@main
struct CoachWidgets: WidgetBundle {
    var body: some Widget {
        CoachAlarmWidget()
    }
}
```

## Common mistakes

- **No `NSAlarmKitUsageDescription`.** Nothing can be scheduled.
- **Skipping authorization.** Ask early with `requestAuthorization()` and give
  `.denied` a real screen.
- **Recurring timers.** Timers are one-shot. Use `.alarm` with
  `.weekly([...])` for repetition.
- **Countdown without the widget extension.** Alarms can be dismissed before
  they ring; the fallback UI covers very little.
- **Hand-tracking state.** Alarms change state while the app is suspended.
  Read it from `alarmUpdates`.
- **Treating `stopIntent` or `secondaryIntent` as required.** Leave both out
  for the standard Stop and Snooze.
- **Pulling other features into AlarmKit.** Route them as listed under Hand-offs.
- **Heavy metadata.** Keep `AlarmMetadata` small or `nil`; keep large data in
  the app and refer to it by ID.
- **The deprecated `stopButton` argument.** Use
  `AlarmPresentation.Alert(title:secondaryButton:secondaryButtonBehavior:)`
  (iOS 26.1+); keep the `stopButton:` form only in a 26.0 fallback branch.

## Review checklist

- [ ] `NSAlarmKitUsageDescription` is present and not empty
- [ ] Authorization is requested and `.denied` has UI
- [ ] `AlarmPresentation` covers every state the app uses (alert, countdown, paused)
- [ ] Any countdown has a matching widget extension whose `ActivityConfiguration` names the same `AlarmAttributes<Metadata>`
- [ ] Metadata conforms to `AlarmMetadata`, stays small, and is `nil` if there is none
- [ ] Each alarm ID is saved for later cancel, pause, resume or stop
- [ ] `alarmUpdates` is observed
- [ ] `stopIntent` and `secondaryIntent` are omitted for standard behavior and only passed for cleanup or custom work
- [ ] `postAlert` is set when `.countdown` snooze is used
- [ ] AlarmKit is credited only with authorization, `AlarmManager` scheduling and state, attributes, presentation, presentation state, sound and system alarm actions
- [ ] The ringing screen is described as drawn by the system
- [ ] Custom countdown and paused UI lives in the widget extension with the same attributes and `AlarmPresentationState`
- [ ] Hand-offs to `widgetkit`, `live-activities` and `push-notifications` are explicit
- [ ] Setup cites only documented requirements; no `com.apple.developer.alarmkit` unless Apple documents it
- [ ] `tintColor` is set on `AlarmAttributes` so the alarm is recognisable
- [ ] `AlarmManager.AlarmError.maximumLimitReached` is handled
- [ ] Sound and vibration are tested on a device, not only in Simulator

## References

- [AlarmKit patterns](references/alarmkit-patterns.md) - complete alarm and timer flows, authorization manager, state store, widget extension, recurrence, snooze and custom actions, Info.plist, errors
- [AlarmKit](https://developer.apple.com/documentation/alarmkit)
- [AlarmManager](https://developer.apple.com/documentation/alarmkit/alarmmanager)
- [AlarmAttributes](https://developer.apple.com/documentation/alarmkit/alarmattributes)
- [Apple sample: scheduling alarms](https://developer.apple.com/documentation/alarmkit/scheduling-an-alarm-with-alarmkit)
