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
:
{
Image
(
systemName
:
"alarm"
)
}
}
}
}
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
(
Array
(
weekdays
)
)
)
)
let
alert
=
AlarmPresentation
.
Alert
(
title
:
"Alarm"
,
stopButton
:
.
stopButton
,
secondaryButton
:
.
snoozeButton
,
secondaryButtonBehavior
:
.
countdown
)
struct
EmptyMetadata
:
AlarmMetadata
{
}
let
config
=
AlarmManager
.
AlarmConfiguration
(
countdownDuration
:
Alarm
.
CountdownDuration
(
preAlert
:
nil
,
postAlert
:
9
*
60
)
,
schedule
:
schedule
,
attributes
:
AlarmAttributes
(
presentation
:
AlarmPresentation
(
alert
:
alert
)
,
metadata
:
EmptyMetadata
(
)
,
tintColor
:
.
blue
)
,
sound
:
.
default
)
_
=
try
?
await
manager
.
schedule
(
id
:
UUID
(
)
,
configuration
:
config
)
}
}
func
cancel
(
id
:
UUID
)
{
Task
{
try
?
await
manager
.
cancel
(
id
:
id
)
}
}
func
togglePause
(
id
:
UUID
,
isPaused
:
Bool
)
{
Task
{
if
isPaused
{
try
?
await
manager
.
resume
(
id
:
id
)
}
else
{
try
?
await
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