cordova-plugin-local-notification: scheduling local notifications in Cordova apps

What the plugin does and who it is for

A local notification is issued by the device, not by a server. The README describes it as a message shown outside the app's normal UI, first as an icon in the notification area and then in the notification drawer, which the user opens to read the details. The plugin exposes that system behaviour to Cordova's JavaScript layer, so a hybrid app can post a notification, schedule one for a later time, and query what is already scheduled.

The audience is narrow and specific. You are building a Cordova app, you target Android 7.0 or newer and iOS 11.3 or newer, and you want reminders, alarms or re-engagement messages that do not depend on a push service. If your app is not Cordova, or if you need remote push, this plugin is the wrong layer. The README also states its platform support plainly: Android 7.0+ with a minimum WebView version of 60, and iOS 11.3+.

The cordova.plugins.notification.local API and how scheduling works

The plugin creates the object cordova.plugins.notification.local, available after the deviceready event. A notification is a plain object with properties such as id, title and text, plus platform-specific keys. The README shows the single-notification call and a second form that takes an array, so batch scheduling is one API call rather than a loop of calls.

IDs are the part that catches people out. The README is explicit: you must set a unique ID for every notification, the plugin does not generate one, and if you omit it the value defaults to 1. Reusing an ID cancels the previously scheduled notification with that ID. That makes IDs a small piece of application state you have to manage, not an implementation detail the plugin hides.

Each platform caps how many notifications can be scheduled at once: 64 on iOS and 500 on Android. The README notes that repeating notifications count as a single notification. If your design schedules one entry per calendar day for a year, iOS will not hold it.

Permissions differ by platform. On iOS and Android 13+, the README states permissions are requested from the user automatically when you schedule a notification, and requestPermission and hasPermission are available if you want to drive that yourself. On Android versions before 13, no permission is required. Android 8 and later also require notification channels; the plugin creates a default channel if you do not create one, or you can call createChannel.

Installing cordova-plugin-local-notification from npm

The plugin is published on npm under the name cordova-plugin-local-notification and installs through the Cordova CLI from the project root. The README gives the plain command, a version-pinned form, and Git, branch, tag and commit variants. For a normal project, the plain npm install is what you want.

cordova plugin add cordova-plugin-local-notification

To pin a release, append the version. The recent releases listed for the repository are v1.2.1, v1.2.2 and v1.2.3, while package.json on the default branch reads 1.2.4.

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

If you are testing an unreleased change, the README supports installing straight from Git, including a branch, a tag or a commit hash.

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

A first real use is scheduling one notification with an explicit ID. Run this after deviceready; the plugin requests permission automatically on iOS and Android 13+, so the user should see a permission prompt before the notification is posted.

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

After that call, expect a status bar icon, and the notification in the drawer when the user pulls it down. If nothing appears, check that deviceready has fired and that permission was granted.

Version 1.2.4 and the maintenance fork

The most important line in the README is a warning above everything else. Since plugin version 1.2.4, dated 28th August 2026, continued support happens on the fork cordova-plugin-local-notifications-continued, and the README states this repository will not be maintained anymore. The repository is not archived, and the last push was on 2026-08-29, one day after that version date.

That changes how you should read every other page of the documentation. The install commands still work and the API is unchanged, but bug fixes and platform updates are expected on the fork, not here. The package.json in this repository still carries the original name, version 1.2.4 and the cordova plugin id cordova-plugin-local-notification, and its funding field points at a GitHub Sponsors account. Anyone planning a multi-year app should treat the fork as the live line and this repository as the reference for everything up to 1.2.4.

The upgrade history is worth reading before you commit to a version, because the plugin has made breaking changes repeatedly. Version 1.0.0 removed the Windows platform, moved to AndroidX, and raised the minimum cordova-android from 6.0.0 to 13.0.0, cordova-ios from 4.3.0 to 7.0.0, Cordova itself from 3.6.0 to 12.0.0, and cordova-plugin-device from 2.0.0 to 3.0.0. Version 1.1.0 renamed Android properties and changed the default channel id from default-channel-id to default_channel. Version 1.1.1 renamed vibrate to androidChannelEnableVibration. These are renames you will feel in your own code, not silent internal changes.

Where the plugin breaks down or is the wrong tool

The scheduling limits are the clearest boundary. Sixty-four pending notifications on iOS is a hard ceiling, and because repeating notifications count as one, a daily reminder is cheap while a year of distinct dated reminders is not. If your feature is a calendar that pre-schedules every event, you need a different strategy on iOS.

Time handling has changed across releases in ways that can surprise you. Version 1.1.4 made Android show notifications whose trigger.at date is in the past when they are scheduled; before that they were ignored. Version 1.1.8 reversed the behaviour again for dates more than 5 seconds in the past, which are now ignored, matching what iOS always did. If your app schedules a notification for a time that may already have passed, the outcome depends on which version you installed, and the README does not document a rollback path for a notification that was dropped.

Platform support is another hard edge. Windows was removed in 1.0.0, so the cordova-windows-plugin topic in the repository metadata no longer reflects what the current version does. The README also warns that Android 8 ships with WebView version 58, below the required minimum of 60, so those devices must update the WebView through Google Play before the plugin will work.

Finally, the maintenance warning is itself a limitation. A plugin whose README says the repository will not be maintained anymore is a dependency you take on deliberately, with a plan for where fixes will come from.

How this differs from a push notification service

The obvious alternative in a Cordova app is a remote push service such as Firebase Cloud Messaging, usually reached through a Cordova push plugin. The difference is architectural rather than a matter of preference. A push service requires a server that decides when to send, a device token registered with that server, and a network path to the device. The notification arrives because something remote asked for it.

This plugin runs entirely on the device. The app schedules a notification with a title, text and trigger, and the operating system delivers it at that time. No token, no server, no connectivity. That makes it the right choice for reminders and alarms that are derived from data the app already has, and the wrong choice for messages that originate elsewhere, such as a chat message or a marketing send. The two are not mutually exclusive: an app can use this plugin for local reminders and a push service for server-driven messages, and the README does not present the plugin as a replacement for either.

Licence and the cost of upgrading

The plugin is licensed under Apache-2.0, and the LICENSE file sits at the top level of the repository alongside package.json and plugin.xml. Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that you keep the licence and notice files when you redistribute. That is a summary of the licence text, not legal advice, and if you ship a modified copy you should read the terms yourself.

The upgrade cost is where this plugin asks for real attention. The cordovaDependencies block in package.json records two compatibility gates: the 0.9.0-beta.3 line, which allowed Cordova 3.6.0 and cordova-android 6.0.0, and the 1.0.0 line, which requires Cordova 12.0.0, cordova-android 13.0.0, cordova-ios 7.0.0 and cordova-plugin-device 3.0.0. Moving from the old line to the new one is a platform upgrade, not a plugin upgrade.

Within the 1.x line, the property renames carry migration work. The default channel id changed from default-channel-id to default_channel in 1.1.0, and the README notes that upgrading and scheduling notifications will leave you with two channels, the old and the new, and that deleteChannel can remove the old one. The vibrate property became androidChannelEnableVibration in 1.1.1. On iOS, iOSForeground became true by default in 1.1.0, and 1.1.1 made a notification always appear in the notification center even when iOSForeground is false. Each of those is a behaviour change you would otherwise discover in testing.

Editorial conclusion

Adopt it if you already run cordova-android 13.0.0 or newer and cordova-ios 7.0.0 or newer and need scheduled local notifications without a push backend. Do not adopt it for Windows, which was removed in 1.0.0, or if you need an actively maintained repository, since the README states support continues only on the fork. Before installing, verify your Cordova and platform versions against the cordovaDependencies block in package.json and decide whether to install cordova-plugin-local-notification or the fork.

Frequently asked questions

Official sources

1. Issues
2. katzer/cordova-plugin-local-notifications on GitHub
3. License: Apache-2.0
4. README
5. Releases