@capacitor/local-notifications
The Local Notifications API provides a way to schedule device notifications locally (i.e. without a server sending push notifications).
Installโ
npm install @capacitor/local-notifications@latest-6
npx cap sync
Androidโ
Android 13 requires a permission check in order to send notifications. You are required to call checkPermissions() and requestPermissions() accordingly.
On Android 12 and older it won't show a prompt and will just return as granted.
Starting on Android 12, scheduled notifications won't be exact unless this permission is added to your AndroidManifest.xml:
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
Note that even if the permission is present, users can still disable exact notifications from the app settings. Use checkExactNotificationSetting() to check the the value of the setting. If a user disables this setting, the app will restart and any notification scheduled with an exact alarm will be deleted. If your application depends on exact alarms, be sure to check this setting on app launch (for example, in App.appStateChange) in order to provide fallbacks or alternative behavior.
On Android 14, there is a new permission called USE_EXACT_ALARM. Use this permission to use exact alarms without needing to request permission from the user. This should only be used if the use of exact alarms is central to your app's functionality. Read more about the implications of using this permission here.
From Android 15 onwards, users can install an app in the Private space. Users can lock their private space at any time, which means that push notifications are not shown until the user unlocks it.
It is not possible to detect if an app is installed in the private space. Therefore, if your app shows any critical notifications, inform your users to avoid installing the app in the private space.
For more information about the behavior changes of your app related to the private space, refer to Android documentation.
Configurationโ
On Android, the Local Notifications can be configured with the following options:
| Prop | Type | Description | Since |
|---|---|---|---|
smallIcon | string | Set the default status bar icon for notifications. Icons should be placed in your app's res/drawable folder. The value for this option should be the drawable resource ID, which is the filename without an extension. Only available for Android. | 1.0.0 |
iconColor | string | Set the default color of status bar icons for notifications. Only available for Android. | 1.0.0 |
sound | string | Set the default notification sound for notifications. On Android 26+ it sets the default channel sound and can't be changed unless the app is uninstalled. If the audio file is not found, it will result in the default system sound being played on Android 21-25 and no sound on Android 26+. Only available for Android. | 1.0.0 |
Examplesโ
In capacitor.config.json:
{
"plugins": {
"LocalNotifications": {
"smallIcon": "ic_stat_icon_config_sample",
"iconColor": "#488AFF",
"sound": "beep.wav"
}
}
}
In capacitor.config.ts:
/// <reference types="@capacitor/local-notifications" />
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
plugins: {
LocalNotifications: {
smallIcon: "ic_stat_icon_config_sample",
iconColor: "#488AFF",
sound: "beep.wav",
},
},
};
export default config;
Dozeโ
If the device has entered Doze mode, your application may have restricted capabilities. If you need your notification to fire even during Doze, schedule your notification by using allowWhileIdle: true. Make use of allowWhileIdle judiciously, as these notifications can only fire once per 9 minutes, per app.
APIโ
schedule(...)getPending()registerActionTypes(...)cancel(...)areEnabled()getDeliveredNotifications()removeDeliveredNotifications(...)removeAllDeliveredNotifications()createChannel(...)deleteChannel(...)listChannels()checkPermissions()requestPermissions()changeExactNotificationSetting()checkExactNotificationSetting()addListener('localNotificationReceived', ...)addListener('localNotificationActionPerformed', ...)removeAllListeners()- Interfaces
- Type Aliases
- Enums
schedule(...)โ
schedule(options: ScheduleOptions) => Promise<ScheduleResult>
Schedule one or more local notifications.
| Param | Type |
|---|---|
options | |
Returns:
Promise<ScheduleResult>
Since: 1.0.0
getPending()โ
getPending() => Promise<PendingResult>
Get a list of pending notifications.
Returns:
Promise<PendingResult>
Since: 1.0.0
registerActionTypes(...)โ
registerActionTypes(options: RegisterActionTypesOptions) => Promise<void>
Register actions to take when notifications are displayed.
Only available for iOS and Android.
| Param | Type |
|---|---|
options | |
Since: 1.0.0
cancel(...)โ
cancel(options: CancelOptions) => Promise<void>
Cancel pending notifications.
| Param | Type |
|---|---|
options | |
Since: 1.0.0
areEnabled()โ
areEnabled() => Promise<EnabledResult>
Check if notifications are enabled or not.
Returns:
Promise<EnabledResult>
Since: 1.0.0
getDeliveredNotifications()โ
getDeliveredNotifications() => Promise<DeliveredNotifications>
Get a list of notifications that are visible on the notifications screen.
Returns:
Promise<DeliveredNotifications>
Since: 4.0.0
removeDeliveredNotifications(...)โ
removeDeliveredNotifications(delivered: DeliveredNotifications) => Promise<void>
Remove the specified notifications from the notifications screen.
| Param | Type |
|---|---|
delivered | |
Since: 4.0.0
removeAllDeliveredNotifications()โ
removeAllDeliveredNotifications() => Promise<void>
Remove all the notifications from the notifications screen.
Since: 4.0.0
createChannel(...)โ
createChannel(channel: Channel) => Promise<void>
Create a notification channel.
Only available for Android.
| Param | Type |
|---|---|
channel | |
Since: 1.0.0
deleteChannel(...)โ
deleteChannel(args: { id: string; }) => Promise<void>
Delete a notification channel.
Only available for Android.
| Param | Type |
|---|---|
args | { id: string; } |
Since: 1.0.0
listChannels()โ
listChannels() => Promise<ListChannelsResult>
Get a list of notification channels.
Only available for Android.
Returns:
Promise<ListChannelsResult>
Since: 1.0.0
checkPermissions()โ
checkPermissions() => Promise<PermissionStatus>
Check permission to display local notifications.
Returns:
Promise<PermissionStatus>
Since: 1.0.0
requestPermissions()โ
requestPermissions() => Promise<PermissionStatus>
Request permission to display local notifications.
Returns:
Promise<PermissionStatus>
Since: 1.0.0
changeExactNotificationSetting()โ
changeExactNotificationSetting() => Promise<SettingsPermissionStatus>
Direct user to the application settings screen to configure exact alarms.
In the event that a user changes the settings from granted to denied, the application will restart and any notification scheduled with an exact alarm will be deleted.
On Android < 12, the user will NOT be directed to the application settings screen, instead this function will
return granted.
Only available on Android.
Returns:
Promise<SettingsPermissionStatus>
Since: 6.0.0
checkExactNotificationSetting()โ
checkExactNotificationSetting() => Promise<SettingsPermissionStatus>
Check application setting for using exact alarms.
Only available on Android.
Returns:
Promise<SettingsPermissionStatus>
Since: 6.0.0
addListener('localNotificationReceived', ...)โ
addListener(eventName: 'localNotificationReceived', listenerFunc: (notification: LocalNotificationSchema) => void) => Promise<PluginListenerHandle>
Listen for when notifications are displayed.
| Param | Type |
|---|---|
eventName | 'localNotificationReceived' |
listenerFunc | |
Returns:
Promise<PluginListenerHandle>
Since: 1.0.0
addListener('localNotificationActionPerformed', ...)โ
addListener(eventName: 'localNotificationActionPerformed', listenerFunc: (notificationAction: ActionPerformed) => void) => Promise<PluginListenerHandle>
Listen for when an action is performed on a notification.
| Param | Type |
|---|---|
eventName | 'localNotificationActionPerformed' |
listenerFunc | |
Returns:
Promise<PluginListenerHandle>
Since: 1.0.0
removeAllListeners()โ
removeAllListeners() => Promise<void>
Remove all listeners for this plugin.
Since: 1.0.0
Interfacesโ
ScheduleResultโ
| Prop | Type | Description | Since |
|---|---|---|---|
notifications | LocalNotificationDescriptor[] | The list of scheduled notifications. | 1.0.0 |
LocalNotificationDescriptorโ
The object that describes a local notification.
| Prop | Type | Description | Since |
|---|---|---|---|
id | number | The notification identifier. | 1.0.0 |