cordova-plugin-local-notifications

Cordova Plugin Local Notifications

) )

[!WARNING] Since plugin version 1.2.4 (28th August 2026) this plugin will get continued support on the fork cordova-plugin-local-notifications-continued. This repository will not be maintained anymore.

A notification is a message you display to the user outside of your app's normal UI. When you tell the system to issue a notification, it first appears as an icon in the notification area. To see the details of the notification, the user opens the notification drawer. Both the notification area and the notification drawer are system-controlled areas that the user can view at any time.

Notification components

• Header area
• Content area
• Action area

How notifications may be noticed

• Showing a status bar icon
• Appearing on the lock screen
• Playing a sound or vibrating
• Peeking onto the current screen
• Blinking the device's LED

Supported platforms

• Android 7.0+ (minimum version by cordova-android 13.0.0) with a minimum WebView Version 60 (Android 8 is shipped with a WebView version 58 and must be updated with Google Play Store before)
• iOS 11.3+ (minimum version by cordova-ios 7.0.0)

Installation

The plugin can be installed via [Cordova-CLI][CLI] and is publicly available on [NPM][npm].

NPM

Execute from the projects root folder:

$ cordova plugin add cordova-plugin-local-notification

Install a specific version:

$ cordova plugin add cordova-plugin-local-notification@VERSION

Git

Install the latest head version:

$ cordova plugin add https://github.com/katzer/cordova-plugin-local-notifications.git

Install from a branch:

$ cordova plugin add https://github.com/katzer/cordova-plugin-local-notifications.git#branch

Install from a tag:

$ cordova plugin add https://github.com/katzer/cordova-plugin-local-notifications.git#v1.0.0

Install from a specific commit:

$ cordova plugin add https://github.com/katzer/cordova-plugin-local-notifications.git#5e4f131

Local

Install from local source:

$ cordova plugin add <path> --nofetch --nosave --link

Upgrade Notice

Version 0.9.0-beta.3 (13.02.2018)

• Last version which supports cordova-android older than 13.0.0 and supports minimum cordova-android version 6.0.0 which is Android version 4.1
• Last version which supports the Windows platform

Version 1.0.0 (17.08.2024)

• Removed Windows platform
• Support for Android 12-14 and uses AndroidX
• Raised minimum cordova-androidversion from 6.0.0 to 13.0.0, which raised the minimum Android version from 4.1 SDK 16 to 7.0 SDK 24
• Raised minimum cordova-ios version from 4.3.0 to 7.0.0
• Raised minimum Cordova version from 3.6.0 to 12.0.0
• Raised minimum cordova-plugin-device version from 2.0.0 to 3.0.0

Updates in version 1.1.0 (23.12.2024)

• Proper handling of Android channels
• Properties were renamed for the Android platform, see Changed properties.

Android

The Default channel id was changed from default-channel-id to default_channel. If you upgrade to this version and schedule notifications, there will be two channels from then on, the old one and the new one. You can remove the old one with deleteChannel.

iOS

iOSForeground is true by default

Updates in version 1.1.1

Android

The property vibrate was renamed to androidChannelEnableVibration.

iOS

A notification will be always showed in the notification center like on Android. Happens also if iOSForeground is false.

Updates in Version 1.1.4

Android

Notifications with an old trigger.at date will be shown when you schedule them. Before they were ignored.

Updates in Version 1.1.8

• Notifications with trigger.at date more than 5 seconds in the past will be ignored. iOS did always ignore passed notifications.
• If no id of a notification is set, it will default to 1 instead of 0.

Basics

The plugin creates the object cordova.plugins.notification.local and is accessible after the deviceready event has been fired.

You can schedule a single notification as follows:

cordova.plugins.notification.local.schedule({
    id: 1,
    title: 'My first notification',
    text: 'Thats pretty easy...'
});

You have always to set an unique ID for every notification. The plugin does not automatically set an ID. If you do not set an ID, it will default to 1. If you reuse an ID of a previous scheduled notification, the previous one will be canceled.

The plugin allows to schedule multiple notifications at once:

cordova.plugins.notification.local.schedule([
    {
        id: 1,
        title: 'My first notification'
    },
    {
        id: 2,
        title: 'My second notification'
    }
]);

Notification Limits

On each platform are limits about how much notifications can be scheduled:

• iOS: 64
• Android: 500

Repeating notifications count as 1 notification.

Properties

A notification does have a set of configurable properties. See all properties.

Permissions

On iOS and Android 13+ permissions must be requested from the user before notifications can be posted. This is done automatically, when scheduling a notification. If you want do it manually, you can use requestPermission. Please keep in mind, that the user can still change the permission later in the system. If you want to check, if you have still the permission to post notifications, use hasPermission.

On Android, the permissions must be requested since Android 13. In earlier versions no permissions must be granted.

Android specials

Notification channels

Since Android 8 notification channels must be created to post noitifications. A default channel will be created for you, if you do not create one. You can also create your own channel by createChannel or when scheduling a notification. For deleting a channel use deleteChannel.

Inexact alarms since Android 12

Since Android 12 alarms will be scheduled inexact by default. On Android 12 (API level 31) and higher, the system invokes the alarm within one hour of the supplied trigger time, unless any battery-saving restrictions are in effect such as battery saver or Doze. Most apps can schedule tasks and events using inexact alarms to complete several common use cases. If your app's core functionality depends on a precisely-timed alarm — such as for an alarm clock app or a calendar app — then it's OK to use an exact alarm instead.

See Schedule exact alarms, if you want use exact alarms.

See Android documentation for more information.

App hibernation / App unused

If your app runs on Android 12 and newer and the user doesn't interact with your app for 3 months, the system places your app in a hibernation state which will cancel all pending notifications and revokes permissions. When the user interacts with your app again, the app exits hibernation and the notifications will be re-scheduled. It doesn't count as app usage if the user dismisses a notification. If the app is hibernated, the user will get informed about it:

The documentation says that permissions are also revoked, but testing the hibernation behavior on an Android 15 emulator showed, that the app keeps the permission to post notifications.

Notes

• Android introduced this behavior in Android 11 and additionally backported this to Android 6 to 10 through the Google Play Store but only the permissions are revoked and not the pending notifications. Because permissions are only needed since Android 13, this does not affect this plugin. Since Android 12 notifications are also canceled besides revoking the permissions.
• You can manually test the hibernation behavior, see App hibernation > Manually invoke hibernation behavior.
• To see a complete list, what counts as app usage and what not, see App hibernation > App usage.
• 3 months are based on executing adb shell device_config get permissions \ auto_revoke_unused_threshold_millis2 which will return 7776000000 milliseconds on an Android 15 Emulator which are nearly 3 months (~2.96 months).

Manage App hibernation

You can get the status of the setting by calling getUnusedAppRestrictionsStatus. To redirect the user to the setting, call openManageUnusedAppRestrictions. Before opening the setting, you can inform the user about this behavior and explain which setting he has to deactivate. When opening the settings, the system will not scroll to the right entry and the setting is named differently on different Android versions:

Sample Android 12:

On other Android versions it is named differently:

Android 13/14:

Android 15:

Doze and Standby

Android has two power-saving features that extend battery life for users by managing how apps behave when a device isn't connected to a power source: Doze and App Standby. Doze reduces battery consumption by deferring background CPU and network activity for apps when the device is unused for long periods of time. App Standby defers background network activity for apps with no recent user activity.

To fire notifications when the device is in doze mode, you can schedule notifications with the property androidAllowWhileIdle.

App Standby does not affect you when showing a notification.

You can read everything about it in the Android documentatation.

Alarm rescheduling

App Update

Android removes all alarms when the app is updated. The plugin reschedules all alarms by a BroadcastReceiver listening to ACTION_MY_PACKAGE_REPLACED.

Device reboot

Android removes all alarms when the device reboots. The plugin reschedules all alarms by a BroadcastReceiver listening to ACTION_BOOT_COMPLETED, but only after the device has been unlocked.

User grants exact alarms

If you use SCHEDULE_EXACT_ALARM for scheduling exact alarms and the user permits the permission in the "Alarms & Reminders", inexact alarms will be rescheduled as exact alarms. This is done by a BroadcastReceiver listening to ACTION_SCHEDULE_EXACT_ALARM_PERMISSION_STATE_CHANGED. This action will not be called if the user revokes the permission. All exact alarms will be canceled then.

Android 15: Alarms get canceled on Force stop

Since Android 15 all pending alarms will get canceled if the user force stops an app, this is a change