capacitor-alarm

Alarm clock scheduler

Install

npm install capacitor-alarm
npx cap sync

API

• setAlarm(...)
• cancelAlarm(...)
• cancelAllAlarm()
• requestExactAlarmPermission()
• requestNotificationPermission()
• checkNotificationPermission()
• checkExactAlarmPermission()
• getAlarms()
• pickAlarmSound()
• stopAlarm()
• addListener('alarmTriggered', ...)
• addListener('alarmNotificationTapped', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

Main Capacitor Alarm Plugin Interface.

setAlarm(...)

setAlarm(alarm: Alarm) => Promise<Alarm>

Schedule an alarm.

Supports:

• Exact timestamp alarms
• Repeating alarms
• Weekly calendar alarms

Examples

One-time alarm

await capacitorExactAlarmPlugin.setAlarm({
  timestamp: Date.now() + 10_000,
  title: "One-time <a href="#alarm">Alarm</a>",
  msg: "This alarm will ring once.",
  soundName: "content://media/internal/audio/media/21"
});

Repeating alarm (every 15 minutes)

await capacitorExactAlarmPlugin.setAlarm({
  repeatInterval: 1000 * 60 * 15,
  title: "Repeating <a href="#alarm">Alarm</a>",
  msg: "This alarm repeats every 15 minutes.",
  soundName: "content://media/internal/audio/media/33"
});

Weekly alarm (every Monday at 7:30)

await capacitorExactAlarmPlugin.setAlarm({
  <a href="#calendar">calendar</a>: {
    weekday: <a href="#weekday">Weekday.Monday</a>,
    hour: 7,
    minute: 30,
  },
  title: "Weekly <a href="#alarm">Alarm</a>",
  msg: "It's Monday at 7:30!",
  soundName: "content://media/internal/audio/media/12"
});

| Param | Type | | ----------- | --------------------------------------- | | alarm | Alarm |

Returns: Promise<Alarm>

cancelAlarm(...)

cancelAlarm(alarm: cancelAlarm) => Promise<void>

Cancel a specific alarm using its ID.

await capacitorExactAlarmPlugin.<a href="#cancelalarm">cancelAlarm</a>({ alarmId: 1 });

| Param | Type | | ----------- | --------------------------------------------------- | | alarm | cancelAlarm |

cancelAllAlarm()

cancelAllAlarm() => Promise<void>

Cancel all scheduled alarms.

await capacitorExactAlarmPlugin.cancelAllAlarm();

requestExactAlarmPermission()

requestExactAlarmPermission() => Promise<void>

Request permission for exact alarms (Android 12+).

await capacitorExactAlarmPlugin.requestExactAlarmPermission();

requestNotificationPermission()

requestNotificationPermission() => Promise<void>

Request notification permission (Android 13+).

await capacitorExactAlarmPlugin.requestNotificationPermission();

checkNotificationPermission()

checkNotificationPermission() => Promise<checkResult>

Check notification permission status.

const res = await capacitorExactAlarmPlugin.checkNotificationPermission();
console.log(res.hasPermission);

Returns: Promise<checkResult>

checkExactAlarmPermission()

checkExactAlarmPermission() => Promise<checkResult>

Check exact alarm permission status.

const res = await capacitorExactAlarmPlugin.checkExactAlarmPermission();
console.log(res.hasPermission);

Returns: Promise<checkResult>

getAlarms()

getAlarms() => Promise<alarmResult>

Retrieve all currently scheduled alarms.

const { alarms } = await capacitorExactAlarmPlugin.getAlarms();
console.log(alarms);

Returns: Promise<alarmResult>

pickAlarmSound()

pickAlarmSound() => Promise<AlarmSoundResult>

Open the Android ringtone picker and return the selected sound URI.

const sound = await capacitorExactAlarmPlugin.pickAlarmSound();
console.log("Selected sound:", sound.uri);

Returns: Promise<AlarmSoundResult>

stopAlarm()

stopAlarm() => Promise<void>

Stop the currently ringing alarm sound.

await capacitorExactAlarmPlugin.stopAlarm();

addListener('alarmTriggered', ...)

addListener(eventName: "alarmTriggered", listenerFunc: (data: Alarm) => void) => Promise<PluginListenerHandle>

Triggered when an alarm fires.

capacitorExactAlarmPlugin.addListener("alarmTriggered", (alarm) => {
  console.log("<a href="#alarm">Alarm</a> fired:", alarm);
});

| Param | Type | | ------------------ | ---------------------------------------------------------- | | eventName | 'alarmTriggered' | | listenerFunc | (data: Alarm) => void |

Returns: Promise<PluginListenerHandle>

addListener('alarmNotificationTapped', ...)

addListener(eventName: "alarmNotificationTapped", listenerFunc: (data: Alarm) => void) => Promise<PluginListenerHandle>

Triggered when the user taps the alarm notification.

capacitorExactAlarmPlugin.addListener("alarmNotificationTapped", (alarm) => {
  console.log("Notification tapped:", alarm);
});

| Param | Type | | ------------------ | ---------------------------------------------------------- | | eventName | 'alarmNotificationTapped' | | listenerFunc | (data: Alarm) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all registered listeners.

await capacitorExactAlarmPlugin.removeAllListeners();

Interfaces

calendar

Calendar Schedule Properties

| Property | Type | Description | |----------|----------------|-------------| | weekday | Weekday | Day of the week (Sunday–Saturday). | | hour | number | Hour (0–23). | | minute | number | Minute (0–59). |

| Prop | Type | | ------------- | ------------------------------------------- | | weekday | Weekday | | hour | number | | minute | number |

cancelAlarm

Payload to cancel an alarm.

| Prop | Type | | ------------- | ------------------- | | alarmId | number |

checkResult

Permission status object.

| Prop | Type | | ------------------- | -------------------- | | hasPermission | boolean |

alarmResult

Returned when retrieving alarms.

| Prop | Type | | ------------ | -------------------- | | alarms | Alarm[] |

AlarmSoundResult

Returned when selecting an alarm sound.

| Prop | Type | | --------- | ------------------- | | uri | string |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Type Aliases

Alarm

Alarm Properties

| Property | Type | Description | |----------------|------------|-------------| | id | number? | Unique ID of the alarm (auto-generated when created). | | timestamp | number? | Unix timestamp (ms) when the alarm should fire. | | calendar | calendar? | Calendar-based schedule (weekly / monthly / daily). | | repeatInterval | number? | Repeating interval in milliseconds. | | title | string | Notification title. | | msg | string | Notification message. | | soundName | string | URI of the alarm sound. | | icon | string? | Android notification icon name. | | dismissText | string? | Text for the dismiss action button. | | missedText | string? | Text shown for missed alarms. | | data | any? | Additional custom data returned on events. |

{ id?: number; timestamp?: number; calendar?: calendar; repeatInterval?: number; title: string; msg: string; soundName?: string; icon?: string; dismissText?: string; missedText?: string; data?: any; }

Enums

Weekday

| Members | Value | | --------------- | -------------- | | Sunday | 1 | | Monday | 2 | | Tuesday | 3 | | Wednesday | 4 | | Thursday | 5 | | Friday | 6 | | Saturday | 7 |