rn-alarm-kit

🚧 Under Construction 🚧

⚠️ This library is currently under active development and is not yet production-ready.

• 🔨 APIs may change without notice
• 📝 Documentation is being improved
• 🐛 Known issues are being addressed
• ✨ New features are being added

Use at your own risk in production environments.

A React Native module that provides native alarm scheduling capabilities using iOS 26's AlarmKit framework. Create powerful, system-level alarms with one-time or recurring schedules and custom UI presentations.

Platform Support

| Platform | Status | Minimum Version | | -------- | -------------- | --------------- | | iOS | ✅ Supported | iOS 26.0+ | | Android | 🔜 Coming Soon | TBA |

Note: Android support is planned for a future release.

✨ Features

• ✅ Schedule alarms at specific times (24-hour format)
• ✅ One-time or recurring alarms (weekly schedule)
• ✅ Custom alarm UI with title, buttons, and colors
• ✅ Request alarm authorization
• ✅ List all scheduled alarms
• ✅ Update existing alarms
• ✅ Cancel a specific alarm
• ✅ Cancel all alarms
• ✅ Built with Expo Modules for seamless integration

Requirements

• iOS 26.0+
• React Native with Expo
• Xcode 26.0+

Installation

npm install rn-alarm-kit

Or with yarn:

yarn add rn-alarm-kit

iOS Setup

Add the following to your Info.plist:

<key>NSAlarmKitUsageDescription</key>
<string>We'll schedule alerts for alarms you create within our app.</string>

Update your Podfile to set the minimum iOS version:

platform :ios, '26.0'

Then run:

cd ios && pod install

Usage

Request Authorization

Before scheduling alarms, request user authorization:

import ReactNativeAlarmkit from "rn-alarm-kit";

const authorized = await ReactNativeAlarmkit.requestAuthorization();
if (authorized) {
  console.log("Alarm permissions granted");
}

Schedule a One-Time Alarm

// Schedule alarm for 8:30 AM (one-time)
const alarmId = await ReactNativeAlarmkit.scheduleAlarm(
  8, // hour (0-23)
  30, // minute (0-59)
  [], // no repeat days (one-time)
  {
    title: "Wake Up",
    stopButtonText: "Stop",
    textColor: "#FFFFFF",
    tintColor: "#FF0000",
  }
);

console.log("Alarm scheduled:", alarmId);

Schedule a Recurring Alarm

// Schedule alarm for 7:00 AM on Monday, Wednesday, Friday
const alarmId = await ReactNativeAlarmkit.scheduleAlarm(
  7, // hour
  0, // minute
  [2, 4, 6], // days: 1=Sun, 2=Mon, 3=Tue, 4=Wed, 5=Thu, 6=Fri, 7=Sat
  {
    title: "Morning Alarm",
    stopButtonText: "Dismiss",
    textColor: "#FFFFFF",
    tintColor: "#007AFF",
  }
);

Schedule Daily Alarm

// Schedule alarm for 6:00 AM every day
const alarmId = await ReactNativeAlarmkit.scheduleAlarm(
  6, // hour (6:00 AM)
  0, // minute
  [1, 2, 3, 4, 5, 6, 7], // All days of the week
  {
    title: "Daily Wake Up",
    stopButtonText: "Stop",
    textColor: "#FFFFFF",
    tintColor: "#34C759",
  }
);

Weekends Only

// Schedule alarm for 9:00 AM on weekends
const alarmId = await ReactNativeAlarmkit.scheduleAlarm(
  9, // hour (9:00 AM)
  0, // minute
  [1, 7], // 1=Sunday, 7=Saturday
  {
    title: "Weekend Alarm",
    stopButtonText: "Stop",
    textColor: "#FFFFFF",
    tintColor: "#FF9500",
    subtitle: "Sleep in a little",
  }
);

List All Alarms

const alarms = await ReactNativeAlarmkit.listAlarms();

// Returns array of alarm objects:
// [
//   {
//     id: "UUID-STRING",
//     state: "scheduled",
//     scheduledTime: "08:30 (Mon, Wed, Fri)"
//   }
// ]

Cancel an Alarm

await ReactNativeAlarmkit.cancelAlarm("alarm-uuid-string");

Update an Alarm

// Update an existing alarm to 9:15 AM on Tuesday and Thursday
const newAlarmId = await ReactNativeAlarmkit.updateAlarm(
  "alarm-uuid-string", // existing alarm ID
  9, // new hour (0-23)
  15, // new minute (0-59)
  [3, 5] // new repeat days: 3=Tue, 5=Thu
);

Cancel All Alarms

await ReactNativeAlarmkit.cancelAllAlarms();

API Reference

requestAuthorization(): Promise<boolean>

Requests permission to schedule alarms. Returns true if authorized, false otherwise.

scheduleAlarm(hour, minute, repeats, config): Promise<string>

Schedules an alarm and returns its unique ID.

Parameters:

• hour (number, 0-23): Hour in 24-hour format
• minute (number, 0-59): Minute
• repeats (number[]): Array of days to repeat (1=Sunday, 2=Monday, ..., 7=Saturday). Pass an empty array for a one-time alarm.
• config (AlarmConfig): Alarm UI configuration

Returns: Alarm UUID as a string

listAlarms(): Promise<AlarmInfo[]>

Returns all scheduled alarms.

Returns: Array of AlarmInfo objects.

getAlarm(id): Promise<AlarmInfo | null>

Returns a single alarm by its ID, or null if not found.

Parameters:

• id (string): The UUID of the alarm

Returns: An AlarmInfo object or null

cancelAlarm(id): Promise<void>

Cancels a specific alarm by its ID.

Parameters:

• id (string): The UUID of the alarm to cancel

updateAlarm(id, hour, minute, repeats): Promise<string>

Updates an existing alarm's time and repeat schedule.

Parameters:

• id (string): The UUID of the alarm to update
• hour (number, 0-23): New hour in 24-hour format
• minute (number, 0-59): New minute
• repeats (number[]): Array of days to repeat (1=Sunday, 2=Monday, ..., 7=Saturday). Pass an empty array for a one-time alarm.

Returns: The new alarm UUID as a string

cancelAllAlarms(): Promise<void>

Cancels all scheduled alarms.

Events

The module emits events when alarms fire or are dismissed. Subscribe using Expo's event listener API:

import ReactNativeAlarmkit from "rn-alarm-kit";

// Listen for alarm firing (e.g., when the alarm goes off)
const firedSubscription = ReactNativeAlarmkit.addListener(
  "onAlarmFired",
  (event) => {
    console.log("Alarm fired:", event.alarmId);
  }
);

// Listen for alarm dismissal
const dismissedSubscription = ReactNativeAlarmkit.addListener(
  "onAlarmDismissed",
  (event) => {
    console.log("Alarm dismissed:", event.alarmId);
  }
);

// Clean up listeners when done
firedSubscription.remove();
dismissedSubscription.remove();

Event Payloads

• onAlarmFired — { alarmId: string } — Emitted when an alarm fires while the app is in the foreground
• onAlarmDismissed — { alarmId: string } — Emitted when an alarm is dismissed

Types

AlarmConfig

Configuration for the alarm UI presentation.

type AlarmConfig = {
  title: string; // Alarm title displayed to the user
  stopButtonText: string; // Text for the stop/dismiss button
  textColor: string; // Text color as hex string (e.g., "#FFFFFF")
  tintColor: string; // Tint/accent color as hex string (e.g., "#FF0000")
  subtitle?: string; // Optional subtitle text
};

AlarmInfo

Information about a scheduled alarm.

type AlarmInfo = {
  id: string; // Alarm UUID
  state: string; // Current state (e.g., "scheduled", "alerting")
  scheduledTime: string; // Formatted time and repeat days (e.g., "08:30 (Mon, Wed)")
};

AlarmFiredPayload

type AlarmFiredPayload = {
  alarmId: string;
};

AlarmDismissedPayload

type AlarmDismissedPayload = {
  alarmId: string;
};

Example

See the example app for a complete implementation with a UI for:

• Day selection checkboxes
• Time input (hour and minute)
• Alarm listing
• Cancel all functionality

Day Number Reference

When scheduling recurring alarms, use these numbers:

• 1 - Sunday
• 2 - Monday
• 3 - Tuesday
• 4 - Wednesday
• 5 - Thursday
• 6 - Friday
• 7 - Saturday

Time Format

All times use 24-hour format:

• 0 = midnight (12:00 AM)
• 12 = noon (12:00 PM)
• 23 = 11:00 PM

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT

Author

Wael Fadlallah (@wael-fadlallah)

Links

• GitHub Repository
• Report Issues
• Apple AlarmKit Documentation