Skip to content

Latest commit

 

History

History

local-notifications

@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
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(...)

schedule(options: ScheduleOptions) => Promise<ScheduleResult>

Schedule one or more local notifications.

Param Type
options ScheduleOptions

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 RegisterActionTypesOptions

Since: 1.0.0


cancel(...)

cancel(options: CancelOptions) => Promise<void>

Cancel pending notifications.

Param Type
options CancelOptions

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 DeliveredNotifications

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 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 (notification: LocalNotificationSchema) => void

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 (notificationAction: ActionPerformed) => void

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

ScheduleOptions

Prop Type Description Since
notifications LocalNotificationSchema[] The list of notifications to schedule. 1.0.0

LocalNotificationSchema

Prop Type Description Since
title string The title of the notification. 1.0.0
body string The body of the notification, shown below the title. 1.0.0
largeBody string Sets a multiline text block for display in a big text notification style. 1.0.0
summaryText string Used to set the summary text detail in inbox and big text notification styles. Only available for Android. 1.0.0
id number The notification identifier. On Android it's a 32-bit int. So the value should be between -2147483648 and 2147483647 inclusive. 1.0.0
schedule Schedule Schedule this notification for a later time. 1.0.0
sound string Name of the audio file to play when this notification is displayed. Include the file extension with the filename. On iOS, the file should be in the app bundle. On Android, the file should be in res/raw folder. Recommended format is .wav because is supported by both iOS and Android. Only available for iOS and Android < 26. For Android 26+ use channelId of a channel configured with the desired sound. If the sound file is not found, (i.e. empty string or wrong name) the default system notification sound will be used. If not provided, it will produce the default sound on Android and no sound on iOS. 1.0.0
smallIcon string Set a custom status bar icon. If set, this overrides the smallIcon option from Capacitor configuration. 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
largeIcon string Set a large 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 color of the notification icon. Only available for Android. 1.0.0
attachments Attachment[] Set attachments for this notification. 1.0.0
actionTypeId string Associate an action type with this notification. 1.0.0
extra any Set extra data to store within this notification. 1.0.0
threadIdentifier string Used to group multiple notifications. Sets threadIdentifier on the UNMutableNotificationContent. Only available for iOS. 1.0.0
summaryArgument string The string this notification adds to the category's summary format string. Sets summaryArgument on the UNMutableNotificationContent. Only available for iOS. 1.0.0
group string Used to group multiple notifications. Calls setGroup() on NotificationCompat.Builder with the provided value. Only available for Android. 1.0.0
groupSummary boolean If true, this notification becomes the summary for a group of notifications. Calls setGroupSummary() on NotificationCompat.Builder with the provided value. Only available for Android when using group. 1.0.0
channelId string Specifies the channel the notification should be delivered on. If channel with the given name does not exist then the notification will not fire. If not provided, it will use the default channel. Calls setChannelId() on NotificationCompat.Builder with the provided value. Only available for Android 26+. 1.0.0
ongoing boolean If true, the notification can't be swiped away. Calls setOngoing() on NotificationCompat.Builder with the provided value. Only available for Android. 1.0.0
autoCancel boolean If true, the notification is canceled when the user clicks on it. Calls setAutoCancel() on NotificationCompat.Builder with the provided value. Only available for Android. 1.0.0
inboxList string[] Sets a list of strings for display in an inbox style notification. Up to 5 strings are allowed. Only available for Android. 1.0.0
silent boolean If true, notification will not appear while app is in the foreground. Only available for iOS. 5.0.0

Schedule

Represents a schedule for a notification.

Use either at, on, or every to schedule notifications.

Prop Type Description Since
at Date Schedule a notification at a specific date and time. 1.0.0
repeats boolean Repeat delivery of this notification at the date and time specified by at. Only available for iOS and Android. 1.0.0
allowWhileIdle boolean Allow this notification to fire while in Doze Only available for Android 23+. Note that these notifications can only fire once per 9 minutes, per app. 1.0.0
on ScheduleOn Schedule a notification on particular interval(s). This is similar to scheduling cron jobs. Only available for iOS and Android. 1.0.0
every ScheduleEvery Schedule a notification on a particular interval. 1.0.0
count number Limit the number times a notification is delivered by the interval specified by every. 1.0.0

Date

Enables basic storage and retrieval of dates and times.

Method Signature Description
toString () => string Returns a string representation of a date. The format of the string depends on the locale.
toDateString () => string Returns a date as a string value.
toTimeString () => string Returns a time as a string value.
toLocaleString () => string Returns a value as a string value appropriate to the host environment's current locale.
toLocaleDateString () => string Returns a date as a string value appropriate to the host environment's current locale.
toLocaleTimeString () => string Returns a time as a string value appropriate to the host environment's current locale.
valueOf () => number Returns the stored time value in milliseconds since midnight, January 1, 1970 UTC.
getTime () => number Gets the time value in milliseconds.
getFullYear () => number Gets the year, using local time.
getUTCFullYear () => number Gets the year using Universal Coordinated Time (UTC).
getMonth () => number Gets the month, using local time.
getUTCMonth () => number Gets the month of a Date object using Universal Coordinated Time (UTC).
getDate () => number Gets the day-of-the-month, using local time.
getUTCDate () => number Gets the day-of-the-month, using Universal Coordinated Time (UTC).
getDay () => number Gets the day of the week, using local time.
getUTCDay () => number Gets the day of the week using Universal Coordinated Time (UTC).
getHours () => number Gets the hours in a date, using local time.
getUTCHours () => number Gets the hours value in a Date object using Universal Coordinated Time (UTC).
getMinutes () => number Gets the minutes of a Date object, using local time.
getUTCMinutes () => number Gets the minutes of a Date object using Universal Coordinated Time (UTC).
getSeconds () => number Gets the seconds of a Date object, using local time.
getUTCSeconds () => number Gets the seconds of a Date object using Universal Coordinated Time (UTC).
getMilliseconds () => number Gets the milliseconds of a Date, using local time.
getUTCMilliseconds () => number Gets the milliseconds of a Date object using Universal Coordinated Time (UTC).
getTimezoneOffset () => number Gets the difference in minutes between the time on the local computer and Universal Coordinated Time (UTC).
setTime (time: number) => number Sets the date and time value in the Date object.
setMilliseconds (ms: number) => number Sets the milliseconds value in the Date object using local time.
setUTCMilliseconds (ms: number) => number Sets the milliseconds value in the Date object using Universal Coordinated Time (UTC).
setSeconds (sec: number, ms?: number | undefined) => number Sets the seconds value in the Date object using local time.
setUTCSeconds (sec: number, ms?: number | undefined) => number Sets the seconds value in the Date object using Universal Coordinated Time (UTC).
setMinutes (min: number, sec?: number | undefined, ms?: number | undefined) => number Sets the minutes value in the Date object using local time.
setUTCMinutes (min: number, sec?: number | undefined, ms?: number | undefined) => number Sets the minutes value in the Date object using Universal Coordinated Time (UTC).
setHours (hours: number, min?: number | undefined, sec?: number | undefined, ms?: number | undefined) => number Sets the hour value in the Date object using local time.
setUTCHours (hours: number, min?: number | undefined, sec?: number | undefined, ms?: number | undefined) => number Sets the hours value in the Date object using Universal Coordinated Time (UTC).
setDate (date: number) => number Sets the numeric day-of-the-month value of the Date object using local time.
setUTCDate (date: number) => number Sets the numeric day of the month in the Date object using Universal Coordinated Time (UTC).
setMonth (month: number, date?: number | undefined) => number Sets the month value in the Date object using local time.
setUTCMonth (month: number, date?: number | undefined) => number Sets the month value in the Date object using Universal Coordinated Time (UTC).
setFullYear (year: number, month?: number | undefined, date?: number | undefined) => number Sets the year of the Date object using local time.
setUTCFullYear (year: number, month?: number | undefined, date?: number | undefined) => number Sets the year value in the Date object using Universal Coordinated Time (UTC).
toUTCString () => string Returns a date converted to a string using Universal Coordinated Time (UTC).
toISOString () => string Returns a date as a string value in ISO format.
toJSON (key?: any) => string Used by the JSON.stringify method to enable the transformation of an object's data for JavaScript Object Notation (JSON) serialization.

ScheduleOn

Prop Type
year number
month number
day number
weekday Weekday
hour number
minute number
second number

Attachment

Represents a notification attachment.

Prop Type Description Since
id string The attachment identifier. 1.0.0
url string The URL to the attachment. Use the res scheme to reference web assets, e.g. res:///assets/img/icon.png. Also accepts file URLs. 1.0.0
options AttachmentOptions Attachment options. 1.0.0

AttachmentOptions

Prop Type Description Since
iosUNNotificationAttachmentOptionsTypeHintKey string Sets the UNNotificationAttachmentOptionsTypeHintKey key in the hashable options of UNNotificationAttachment. Only available for iOS. 1.0.0
iosUNNotificationAttachmentOptionsThumbnailHiddenKey string Sets the UNNotificationAttachmentOptionsThumbnailHiddenKey key in the hashable options of UNNotificationAttachment. Only available for iOS. 1.0.0
iosUNNotificationAttachmentOptionsThumbnailClippingRectKey string Sets the UNNotificationAttachmentOptionsThumbnailClippingRectKey key in the hashable options of UNNotificationAttachment. Only available for iOS. 1.0.0
iosUNNotificationAttachmentOptionsThumbnailTimeKey string Sets the UNNotificationAttachmentOptionsThumbnailTimeKey key in the hashable options of UNNotificationAttachment. Only available for iOS. 1.0.0

PendingResult

Prop Type Description Since
notifications PendingLocalNotificationSchema[] The list of pending notifications. 1.0.0

PendingLocalNotificationSchema

Prop Type Description Since
title string The title of the notification. 1.0.0
body string The body of the notification, shown below the title. 1.0.0
id number The notification identifier. 1.0.0
schedule Schedule Schedule this notification for a later time. 1.0.0
extra any Set extra data to store within this notification. 1.0.0

RegisterActionTypesOptions

Prop Type Description Since
types ActionType[] The list of action types to register. 1.0.0

ActionType

A collection of actions.

Prop Type Description Since
id string The ID of the action type. Referenced in notifications by the actionTypeId key. 1.0.0
actions Action[] The list of actions associated with this action type. 1.0.0
iosHiddenPreviewsBodyPlaceholder string Sets hiddenPreviewsBodyPlaceholder of the UNNotificationCategory. Only available for iOS. 1.0.0
iosCustomDismissAction boolean Sets customDismissAction in the options of the UNNotificationCategory. Only available for iOS. 1.0.0
iosAllowInCarPlay boolean Sets allowInCarPlay in the options of the UNNotificationCategory. Only available for iOS. 1.0.0
iosHiddenPreviewsShowTitle boolean Sets hiddenPreviewsShowTitle in the options of the UNNotificationCategory. Only available for iOS. 1.0.0
iosHiddenPreviewsShowSubtitle boolean Sets hiddenPreviewsShowSubtitle in the options of the UNNotificationCategory. Only available for iOS. 1.0.0

Action

An action that can be taken when a notification is displayed.

Prop Type Description Since
id string The action identifier. Referenced in the 'actionPerformed' event as actionId. 1.0.0
title string The title text to display for this action. 1.0.0
requiresAuthentication boolean Sets authenticationRequired in the options of the UNNotificationAction. Only available for iOS. 1.0.0
foreground boolean Sets foreground in the options of the UNNotificationAction. Only available for iOS. 1.0.0
destructive boolean Sets destructive in the options of the UNNotificationAction. Only available for iOS. 1.0.0
input boolean Use a UNTextInputNotificationAction instead of a UNNotificationAction. Only available for iOS. 1.0.0
inputButtonTitle string Sets textInputButtonTitle on the UNTextInputNotificationAction. Only available for iOS when input is true. 1.0.0
inputPlaceholder string Sets textInputPlaceholder on the UNTextInputNotificationAction. Only available for iOS when input is true. 1.0.0

CancelOptions

Prop Type Description Since
notifications LocalNotificationDescriptor[] The list of notifications to cancel. 1.0.0

EnabledResult

Prop Type Description Since
value boolean Whether or not the device has local notifications enabled. 1.0.0

DeliveredNotifications

Prop Type Description Since
notifications DeliveredNotificationSchema[] List of notifications that are visible on the notifications screen. 1.0.0

DeliveredNotificationSchema

Prop Type Description Since
id number The notification identifier. 4.0.0
tag string The notification tag. Only available on Android. 4.0.0
title string The title of the notification. 4.0.0
body string The body of the notification, shown below the title. 4.0.0
group string The configured group of the notification. Only available for Android. 4.0.0
groupSummary boolean If this notification is the summary for a group of notifications. Only available for Android. 4.0.0
data any Any additional data that was included in the notification payload. Only available for Android. 4.0.0
extra any Extra data to store within this notification. Only available for iOS. 4.0.0
attachments Attachment[] The attachments for this notification. Only available for iOS. 1.0.0
actionTypeId string Action type ssociated with this notification. Only available for iOS. 4.0.0
schedule Schedule Schedule used to fire this notification. Only available for iOS. 4.0.0
sound string Sound that was used when the notification was displayed. Only available for iOS. 4.0.0

Channel

Prop Type Description Default Since
id string The channel identifier. 1.0.0
name string The human-friendly name of this channel (presented to the user). 1.0.0
description string The description of this channel (presented to the user). 1.0.0
sound string The sound that should be played for notifications posted to this channel. Notification channels with an importance of at least 3 should have a sound. The file name of a sound file should be specified relative to the android app res/raw directory. If the sound is not provided, or the sound file is not found no sound will be used. 1.0.0
importance Importance The level of interruption for notifications posted to this channel. 3 1.0.0
visibility Visibility The visibility of notifications posted to this channel. This setting is for whether notifications posted to this channel appear on the lockscreen or not, and if so, whether they appear in a redacted form. 1.0.0
lights boolean Whether notifications posted to this channel should display notification lights, on devices that support it. 1.0.0
lightColor string The light color for notifications posted to this channel. Only supported if lights are enabled on this channel and the device supports it. Supported color formats are #RRGGBB and #RRGGBBAA. 1.0.0
vibration boolean Whether notifications posted to this channel should vibrate. 1.0.0

ListChannelsResult

Prop Type Description Since
channels Channel[] The list of notification channels. 1.0.0

PermissionStatus

Prop Type Description Since
display PermissionState Permission state of displaying notifications. 1.0.0

SettingsPermissionStatus

Prop Type Description Since
exact_alarm PermissionState Permission state of using exact alarms. 6.0.0

PluginListenerHandle

Prop Type
remove () => Promise<void>

ActionPerformed

Prop Type Description Since
actionId string The identifier of the performed action. 1.0.0
inputValue string The value entered by the user on the notification. Only available on iOS for notifications with input set to true. 1.0.0
notification LocalNotificationSchema The original notification schema. 1.0.0

Type Aliases

ScheduleEvery

'year' | 'month' | 'two-weeks' | 'week' | 'day' | 'hour' | 'minute' | 'second'

Importance

The importance level. For more details, see the Android Developer Docs

1 | 2 | 3 | 4 | 5

Visibility

The notification visibility. For more details, see the Android Developer Docs

-1 | 0 | 1

PermissionState

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

Enums

Weekday

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