react-native-alarm-scheduler

Real, user-visible alarms for React Native and Expo — AlarmKit on iOS, an equivalent on Android.

iOS 26 shipped AlarmKit: an alarm that rings on the lock screen, through silent mode and Focus, whether or not your app is running. Android ships no such framework. This package gives you AlarmKit on iOS and builds the equivalent on Android out of AlarmManager.setAlarmClock, a foreground service that keeps ringing through Doze and a killed app, and a full-screen lock-screen ring UI — behind one typed API.

Notification libraries schedule a notification and hope the device is awake to show it. This schedules an actual alarm.

Features

• ⏰ App-owned native alarms on Android and iOS from one typed API.
• 🔒 Ring until your app says stop — with openAppOnly, only completeNativeAlarmAsync() ends it.
• 📢 Stays audible on Android — loops on the alarm stream, ignoring the ringer and Do Not Disturb, and re-raises the volume when anything lowers it.
• 📱 Full-screen lock-screen ringing UI backed by a foreground service, so a killed app still rings.
• 🔁 Survives reboots, app updates, and clock/timezone changes.
• 🧭 Cold-launch handoff records written natively before any JS runs, so your app always knows why it opened.
• 🎵 User-selected alarm sounds — pass a picker URI at runtime; each alarm can use a different local audio file.
• 🔇 Silent alarms — suppress audio while preserving native alarm presentation and optional vibration.
• 🕐 System Clock integration on Android via ACTION_SET_ALARM and ACTION_SHOW_ALARMS.
• 🧩 Expo config plugin for permissions and NSAlarmKitUsageDescription.
• 🔷 Fully typed TypeScript API, with explicit unavailable behavior where the OS cannot schedule alarms.

Documentation

📖 Documentation — guides for scheduling, handoffs, and sounds.

• API reference — every method, type, and event.
• Platform behavior — Android ringing internals and iOS AlarmKit limits.
• Example app — a runnable Expo app exercising the full API.
• For AI agents — llms.txt, raw markdown per page, and a bundled agent skill.

Requirements

• An Expo or bare React Native app with native prebuild support — this module uses native code, so it does not work in Expo Go.
• Expo SDK 57 or 58.
• Android API 24+.
• iOS 16.4+ for compatibility; iOS 26 SDK and runtime for actual AlarmKit scheduling.

Bare React Native apps need Expo Modules installed first.

Installation

npm install react-native-alarm-scheduler

Add the config plugin to your app config, then rebuild:

{
  "expo": {
    "plugins": [
      [
        "react-native-alarm-scheduler",
        { "alarmKitUsageDescription": "Allow this app to schedule alarms." }
      ]
    ]
  }
}

npx expo prebuild
npx expo run:android

All plugin options are listed in the installation docs.

Usage

import AlarmScheduler from 'react-native-alarm-scheduler';

const permissions = await AlarmScheduler.requestPermissionsAsync();

if (permissions.canScheduleExactAlarms) {
  const alarm = await AlarmScheduler.scheduleAlarmAsync({
    hour: 7,
    minute: 30,
    title: 'Morning alarm',
    weekdays: [1, 2, 3, 4, 5], // ISO: 1 = Monday, 7 = Sunday
  });

  await AlarmScheduler.cancelAlarmAsync(alarm.id);
}

List and cancel what you scheduled:

const alarms = await AlarmScheduler.getScheduledAlarmsAsync();

for (const alarm of alarms) {
  await AlarmScheduler.cancelAlarmAsync(alarm.id);
}

Routing when an alarm opens your app

Events (onAlarmTriggered, onAlarmAction, onAlarmStateChange) fire only when a JS runtime is alive — which it is not on a cold launch from the lock screen. Everything they carry is also written natively before any JS runs, so reconcile from the async getters on every launch and foreground:

const handoff = await AlarmScheduler.getPendingNativeAlarmHandoffAsync();
const context = handoff ? null : await AlarmScheduler.getCurrentAlarmContextAsync();
const alarmId = handoff?.alarmId ?? context?.id;

if (alarmId) {
  router.replace(`/alarm/${alarmId}`);
  await AlarmScheduler.clearPendingNativeAlarmHandoffAsync();
}

See the API reference.

Ringing until your app says stop

Set alertActionMode: 'openAppOnly' and the ringing alert loses its stop button — the only way out opens your app, and the alarm keeps ringing until you call completeNativeAlarmAsync(alarmId). Useful when "the user pressed stop" is not proof of anything:

await AlarmScheduler.scheduleAlarmAsync({
  hour: 7,
  minute: 0,
  title: 'Wake up',
  // Android inherits every shared iOS field; set android only where platforms differ.
  ios: { alertActionMode: 'openAppOnly', stopIntentBehavior: 'rescheduleImmediate' },
  android: { maxRingDurationSeconds: 0 },
});

The guarantee is absolute on Android and best-effort on iOS — see Completion gating.

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗