alarm

This plugins allow Capacitor to manage alarms. Heavily (almost entirely) inspired by the Alarm Flutter plugin.

Install

export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jbr/Contents/Home
npm install alarm
npx cap sync

API

• setAlarm(...)
• stopAlarm(...)
• stopAll()
• isRinging(...)
• getAlarms()
• getRingingAlarms()
• setWarningNotificationOnKill(...)
• checkPermissions()
• requestPermissions()
• requestFullScreenIntentPermission()
• addListener('alarmRang', ...)
• addListener('alarmStopped', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

setAlarm(...)

setAlarm(options: { alarmSettings: AlarmSettings; }) => any

Set an alarm with the specified settings

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | { alarmSettings: AlarmSettings; } |

Returns: any

stopAlarm(...)

stopAlarm(options: { alarmId: number; }) => any

Stop a specific alarm by ID

| Param | Type | | ------------- | --------------------------------- | | options | { alarmId: number; } |

Returns: any

stopAll()

stopAll() => any

Stop all active alarms

Returns: any

isRinging(...)

isRinging(options: { alarmId?: number; }) => any

Check if an alarm is currently ringing

| Param | Type | | ------------- | ---------------------------------- | | options | { alarmId?: number; } |

Returns: any

getAlarms()

getAlarms() => any

Get all scheduled alarms

Returns: any

getRingingAlarms()

getRingingAlarms() => any

Get all currently ringing alarms with their full settings

Returns: any

setWarningNotificationOnKill(...)

setWarningNotificationOnKill(options: { title: string; body: string; }) => any

Set warning notification when app is killed

| Param | Type | | ------------- | --------------------------------------------- | | options | { title: string; body: string; } |

Returns: any

checkPermissions()

checkPermissions() => any

Check current permission status

Returns: any

requestPermissions()

requestPermissions() => any

Request permissions for notifications

Returns: any

requestFullScreenIntentPermission()

requestFullScreenIntentPermission() => any

Request full screen intent permission on Android This is required for alarms to show properly on Android 14+ If the permission is denied, we have to ask the request

Returns: any

addListener('alarmRang', ...)

addListener(eventName: 'alarmRang', listenerFunc: (data: { alarmId: number; }) => void) => any

Add listener for alarm ring events

| Param | Type | | ------------------ | ---------------------------------------------------- | | eventName | 'alarmRang' | | listenerFunc | (data: { alarmId: number; }) => void |

Returns: any

addListener('alarmStopped', ...)

addListener(eventName: 'alarmStopped', listenerFunc: (data: { alarmId: number; }) => void) => any

Add listener for alarm stop events

| Param | Type | | ------------------ | ---------------------------------------------------- | | eventName | 'alarmStopped' | | listenerFunc | (data: { alarmId: number; }) => void |

Returns: any

removeAllListeners()

removeAllListeners() => any

Remove all listeners for this plugin

Returns: any

Interfaces

AlarmSettings

| Prop | Type | Description | Default | | ----------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- | ------------------ | | id | number | Unique identifier of the alarm | | | dateTime | string | The date and time when the alarm should ring (ISO string) | | | assetAudioPath | string | The path to audio asset for the alarm ringtone | | | volumeSettings | VolumeSettings | Volume settings for the alarm | | | notificationSettings | NotificationSettings | Notification settings for the alarm | | | loopAudio | boolean | Whether to loop the audio indefinitely | true | | vibrate | boolean | Whether to vibrate when alarm rings | true | | warningNotificationOnKill | boolean | Whether to show warning notification when app is killed | true | | androidFullScreenIntent | boolean | Whether to use full screen intent on Android | true | | allowAlarmOverlap | boolean | Whether to allow alarm overlap | false | | iOSBackgroundAudio | boolean | Whether to enable background audio on iOS | true | | androidStopAlarmOnTermination | boolean | Whether to stop alarm when Android task is terminated | true | | payload | string | Optional payload data | |

VolumeSettings

| Prop | Type | Description | Default | | -------------------- | -------------------- | ------------------------------------------------------- | ------------------ | | volume | number | System volume level (0.0 to 1.0) | | | fadeDuration | number | Duration over which to fade the alarm (in milliseconds) | | | fadeSteps | {} | Volume fade steps for custom fade patterns | | | volumeEnforced | boolean | Whether to enforce the volume setting | false |

VolumeFadeStep

| Prop | Type | Description | | ------------ | ------------------- | -------------------------------------- | | time | number | Time in milliseconds from alarm start | | volume | number | Volume level at this time (0.0 to 1.0) |

NotificationSettings

| Prop | Type | Description | | ---------------- | ------------------- | ----------------------------------------------------------- | | title | string | Title of the alarm notification | | body | string | Body of the alarm notification | | stopButton | string | Text for the stop button (null to hide button) | | icon | string | Icon name for the notification (Android only) | | iconColor | string | Color of the notification icon as hex string (Android only) | | image | string | Image to show in the notification |

PermissionStatus

| Prop | Type | Description | | ------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | notifications | PermissionState | Permission state for notifications | | fullScreen | PermissionState | Permission state fullScreenIntent on Android If the permission is denied, we have to ask the request |

PluginListenerHandle

| Prop | Type | | ------------ | ------------------------- | | remove | () => any |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'