Skip to main content
Version: v2

Local Notifications

Local Notifications

The Local Notification API provides a way to schedule "local" notifications - notifications that are scheduled and delivered on the device as opposed to "push" notifications sent from a server.

Local Notifications are great for reminding the user about a change in the app since they last visited, providing reminder features, and delivering offline information without the app being in the foreground.

Example

import { Plugins } from '@capacitor/core';
const { LocalNotifications } = Plugins;

const notifs = await LocalNotifications.schedule({
notifications: [
{
title: 'Title',
body: 'Body',
id: 1,
schedule: { at: new Date(Date.now() + 1000 * 5) },
sound: null,
attachments: null,
actionTypeId: '',
extra: null,
},
],
});
console.log('scheduled notifications', notifs);

Local Notifications configuration (Android only)

The local notification plugin allows the following configuration values to be added in capacitor.config.json for the Android platform:

  • smallIcon: It allows you to set the default icon for the local notification.
  • iconColor: It allows you to set the default color for the local notification icon.
  • sound: It allows you to set the default notification sound. On Android 26+ it sets the default channel sound and can't be changed unless the app is uninstalled.
 "plugins": {
"LocalNotifications": {
"smallIcon": "ic_stat_icon_config_sample",
"iconColor": "#488AFF",
"sound": "beep.wav"
}
}

API

schedule(...)

schedule(options: { notifications: LocalNotification[]; }) => Promise<LocalNotificationScheduleResult>
ParamType
options{ notifications: LocalNotification[]; }

Returns: Promise<LocalNotificationScheduleResult>


getPending()

getPending() => Promise<LocalNotificationPendingList>

Returns: Promise<LocalNotificationPendingList>


registerActionTypes(...)

registerActionTypes(options: { types: LocalNotificationActionType[]; }) => Promise<void>
ParamType
options{ types: LocalNotificationActionType[]; }

cancel(...)

cancel(pending: LocalNotificationPendingList) => Promise<void>
ParamType
pendingLocalNotificationPendingList

areEnabled()

areEnabled() => Promise<LocalNotificationEnabledResult>

Returns: Promise<LocalNotificationEnabledResult>


createChannel(...)

createChannel(channel: NotificationChannel) => Promise<void>
ParamType
channelNotificationChannel

deleteChannel(...)

deleteChannel(channel: NotificationChannel) => Promise<void>
ParamType
channelNotificationChannel

listChannels()

listChannels() => Promise<NotificationChannelList>

Returns: Promise<NotificationChannelList>


requestPermission()

requestPermission() => Promise<NotificationPermissionResponse>

Returns: Promise<NotificationPermissionResponse>


addListener(...)

addListener(eventName: 'localNotificationReceived', listenerFunc: (notification: LocalNotification) => void) => PluginListenerHandle
ParamType
eventName"localNotificationReceived"
listenerFunc(notification: LocalNotification) => void

Returns: PluginListenerHandle


addListener(...)

addListener(eventName: 'localNotificationActionPerformed', listenerFunc: (notificationAction: LocalNotificationActionPerformed) => void) => PluginListenerHandle
ParamType
eventName"localNotificationActionPerformed"
listenerFunc(notificationAction: LocalNotificationActionPerformed) => void

Returns: PluginListenerHandle


removeAllListeners()

removeAllListeners() => void

Remove all native listeners for this plugin


Interfaces

LocalNotificationScheduleResult

LocalNotification

PropTypeDescription
titlestring
bodystring
idnumber
scheduleLocalNotificationSchedule
soundstringName of the audio file with extension. On iOS the file should be in the app bundle. On Android the file should be on res/raw folder. Doesn't work on Android version 26+ (Android O and newer), for Recommended format is .wav because is supported by both platforms.
smallIconstringAndroid-only: set a custom statusbar icon. If set, it overrides default icon from capacitor.config.json
iconColorstringAndroid only: set the color of the notification icon
attachmentsLocalNotificationAttachment[]
actionTypeIdstring
extraany
threadIdentifierstringiOS only: set the thread identifier for notification grouping
summaryArgumentstringiOS 12+ only: set the summary argument for notification grouping
groupstringAndroid only: set the group identifier for notification grouping, like threadIdentifier on iOS.
groupSummarybooleanAndroid only: designate this notification as the summary for a group (should be used with the group property).
channelIdstringAndroid only: set the notification channel on which local notification will generate. If channel with the given name does not exist then the notification will not fire. If not provided, it will use the default channel.
ongoingbooleanAndroid only: set the notification ongoing. If set to true the notification can't be swiped away.
autoCancelbooleanAndroid only: set the notification to be removed automatically when the user clicks on it

LocalNotificationSchedule

PropType
atDate
repeatsboolean
every"year" | "month" | "two-weeks" | "week" | "day" | "hour" | "minute" | "second"
countnumber
on{ year?: number; month?: number; day?: number; hour?: number; minute?: number; }

Date

Enables basic storage and retrieval of dates and times.

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

LocalNotificationAttachment

PropType
idstring
urlstring
optionsLocalNotificationAttachmentOptions

LocalNotificationAttachmentOptions

PropType
iosUNNotificationAttachmentOptionsTypeHintKeystring
iosUNNotificationAttachmentOptionsThumbnailHiddenKeystring
iosUNNotificationAttachmentOptionsThumbnailClippingRectKeystring
iosUNNotificationAttachmentOptionsThumbnailTimeKeystring

LocalNotificationPendingList

PropType
notificationsLocalNotificationRequest[]

LocalNotificationRequest

PropType
idstring

LocalNotificationActionType

PropType
idstring
actionsLocalNotificationAction[]
iosHiddenPreviewsBodyPlaceholderstring
iosCustomDismissActionboolean
iosAllowInCarPlayboolean
iosHiddenPreviewsShowTitleboolean
iosHiddenPreviewsShowSubtitleboolean

LocalNotificationAction

PropType
idstring
titlestring
requiresAuthenticationboolean
foregroundboolean
destructiveboolean
inputboolean
inputButtonTitlestring
inputPlaceholderstring

LocalNotificationEnabledResult

PropTypeDescription
valuebooleanWhether the device has Local Notifications enabled or not

NotificationChannel

PropType
idstring
namestring
descriptionstring
soundstring
importance1 | 2 | 5 | 4 | 3
visibility0 | 1 | -1
lightsboolean
lightColorstring
vibrationboolean

NotificationChannelList

PropType
channelsNotificationChannel[]

NotificationPermissionResponse

PropType
grantedboolean

PluginListenerHandle

PropType
remove() => void

LocalNotificationActionPerformed

PropType
actionIdstring
inputValuestring
notificationLocalNotification