Scheduling

`scheduleAlarmAsync(alarm)`

Schedules an app-owned native alarm and returns the stored alarm.

const scheduled = await AlarmScheduler.scheduleAlarmAsync({
  id: '00000000-0000-4000-8000-000000000001',
  hour: 7,
  minute: 30,
  title: 'Morning alarm',
  weekdays: [1, 2, 3, 4, 5],
  soundUri: pickedAudioUri,
  ios: {
    alertTitle: 'Morning alarm',
    secondaryButtonTitle: 'Open',
    stopIntentBehavior: 'rescheduleImmediate',
    secondaryButtonBehavior: 'openApp',
    metadata: { route: 'alarm-detail' },
  },
  android: {
    launchUri: 'myapp://alarm-detail',
    maxRingDurationSeconds: 0,
  },
});

Input

type AlarmScheduleInput = {
  id?: string;
  hour: number;
  minute: number;
  title?: string;
  weekdays?: AlarmWeekday[];
  timestamp?: number;
  showUi?: boolean;
  soundUri?: string;
  ios?: IosAlarmOptions;
  android?: AndroidAlarmOptions;
};

Field	Notes
`id`	Android accepts any string. iOS AlarmKit requires a UUID string. Generated when omitted.
`hour`	24-hour time, `0`–`23`.
`minute`	`0`–`59`.
`weekdays`	ISO numbering: `1` Monday … `7` Sunday. Omit for a one-shot alarm.
`timestamp`	Milliseconds since the Unix epoch. When omitted, the module schedules the next matching `hour`/`minute`.
`soundUri`	Runtime-selected local audio URI. Imported into durable native storage while scheduling.

Returns

type ScheduledAlarm = {
  id: string;
  hour: number;
  minute: number;
  title: string;
  weekdays: AlarmWeekday[];
  timestamp: number;
  platform: 'android' | 'ios';
  metadata?: AlarmMetadata;
};

iOS options

type AlarmAlertActionMode =
  | 'default'
  | 'openAppOnly';

type IosAlarmOptions = {
  metadata?: AlarmMetadata;
  alertTitle?: string;
  alertActionMode?: AlarmAlertActionMode;
  stopButtonTitle?: string;
  secondaryButtonTitle?: string;
  /** Title shown while a deferred or follow-up timer occurrence is counting down. */
  countdownTitle?: string;
  stopIntentBehavior?: 'recordOnly' | 'openApp' | 'rescheduleImmediate';
  secondaryButtonBehavior?: 'openApp' | 'recordOnly' | 'none';
  silent?: boolean;
  soundUri?: string;
  soundName?: string;
};

metadata is stored by the package and included in AlarmKit metadata; the package always adds alarmId and title. silent uses the package’s bundled silent sound and takes precedence over soundUri and soundName. It is supported on physical iOS 26+ devices; the Simulator rejects it instead of falling back to audible audio. soundUri is transcoded into Library/Sounds and takes precedence over soundName. soundName maps directly to AlertConfiguration.AlertSound.named(soundName) and must already exist in the app bundle or Library/Sounds.

See iOS platform behavior for what each stopIntentBehavior and secondaryButtonBehavior value actually does.

Android options

type AndroidAlarmOptions = {
  metadata?: AlarmMetadata;
  alertTitle?: string;
  alertBody?: string;
  alertActionMode?: AlarmAlertActionMode;
  stopButtonTitle?: string;
  secondaryButtonTitle?: string;
  stopIntentBehavior?: 'recordOnly' | 'openApp' | 'rescheduleImmediate';
  secondaryButtonBehavior?: 'openApp' | 'recordOnly' | 'none';
  silent?: boolean;
  soundName?: string;
  soundUri?: string;
  vibrate?: boolean;
  enforceVolume?: boolean;
  restoreVolume?: boolean;
  volume?: number;
  fullScreen?: boolean;
  fullScreenTarget?: 'native' | 'app';
  launchUri?: string;
  maxRingDurationSeconds?: number;
  backupDelaySeconds?: number;
};

Field	Default	Notes
`alertBody`	`"Alarm"`	Secondary line on the ringing screen and notification.
`silent`	`false`	Suppress audio and volume enforcement. Vibration remains controlled by `vibrate`.
`soundName`	—	File in `android/app/src/main/res/raw`, extension optional.
`soundUri`	—	Runtime local URI. Copied into durable private storage and takes precedence over `soundName`.
`vibrate`	`true`
`enforceVolume`	`true`	Pins the alarm stream at `volume` and re-raises it when anything lowers it.
`restoreVolume`	`true`	Restore the user’s previous alarm volume when the ring ends.
`volume`	`1`	Fraction of max alarm volume, `0`–`1`.
`fullScreen`	`true`	Take over the screen, lock screen included.
`fullScreenTarget`	`'native'`	`'app'` only works if your activity sets `showWhenLocked`.
`launchUri`	—	Deep link on handoff. `{alarmId}` is substituted, else `?alarmId=` is appended.
`maxRingDurationSeconds`	`300`	`0` rings until the app completes the alarm.
`backupDelaySeconds`	`1`	Delay when re-arming a backup alarm. Floor `0.1`.

Android inherits the iOS options

metadata, alertTitle, alertActionMode, stopButtonTitle, secondaryButtonTitle, stopIntentBehavior, secondaryButtonBehavior, silent, soundUri and soundName fall back to the matching ios value when omitted. An app written against the AlarmKit flow behaves the same on Android without passing an android block at all.

`cancelAlarmAsync(id)`

Cancels an app-owned alarm by id. Returns true when a native or stored alarm was removed.

const removed = await AlarmScheduler.cancelAlarmAsync(alarmId);

`getScheduledAlarmsAsync()`

Returns the app-owned alarms stored by this module.

const alarms: ScheduledAlarm[] = await AlarmScheduler.getScheduledAlarmsAsync();

Scheduling

scheduleAlarmAsync(alarm)