Skip to content

@tauri-apps/plugin-notification

Send toast notifications (brief auto-expiring OS window element) to your user. Can also be used with the Notification Web API.

function active(): Promise<ActiveNotification[]>;

Defined in: plugins/notification/guest-js/index.ts:796

Retrieves the list of active notifications.

import { active } from '@tauri-apps/plugin-notification';
const activeNotifications = await active();

Promise<ActiveNotification[]>

A promise resolving to the list of active notifications.

2.0.0


function cancel(notifications: number[]): Promise<void>;

Defined in: plugins/notification/guest-js/index.ts:762

Cancels the pending notifications with the given list of identifiers.

import { cancel } from '@tauri-apps/plugin-notification';
await cancel([-34234, 23432, 4311]);
Parameter Type Description
notifications number[] The identifiers of the pending notifications to cancel.

Promise<void>

A promise indicating the success or failure of the operation.

2.0.0


function cancelAll(): Promise<void>;

Defined in: plugins/notification/guest-js/index.ts:779

Cancels all pending notifications.

import { cancelAll } from '@tauri-apps/plugin-notification';
await cancelAll();

Promise<void>

A promise indicating the success or failure of the operation.

2.0.0


function channels(): Promise<Channel[]>;

Defined in: plugins/notification/guest-js/index.ts:899

Retrieves the list of notification channels.

import { channels } from '@tauri-apps/plugin-notification';
const notificationChannels = await channels();

Promise<Channel[]>

A promise resolving to the list of notification channels.

2.0.0


function createChannel(channel: Channel): Promise<void>;

Defined in: plugins/notification/guest-js/index.ts:863

Creates a notification channel.

import { createChannel, Importance, Visibility } from '@tauri-apps/plugin-notification';
await createChannel({
id: 'new-messages',
name: 'New Messages',
lights: true,
vibration: true,
importance: Importance.Default,
visibility: Visibility.Private
});
Parameter Type Description
channel Channel The channel to create.

Promise<void>

A promise indicating the success or failure of the operation.

2.0.0


function isPermissionGranted(): Promise<boolean>;

Defined in: plugins/notification/guest-js/index.ts:647

Checks if the permission to send notifications is granted.

import { isPermissionGranted } from '@tauri-apps/plugin-notification';
const permissionGranted = await isPermissionGranted();

Promise<boolean>

A promise resolving to whether the permission to send notifications is granted.

2.0.0


function onAction(cb: (event: ActionPerformed) => void): Promise<PluginListener>;

Defined in: plugins/notification/guest-js/index.ts:957

Listens to the actions the user performs on a notification.

On mobile it is emitted for notifications that reference an action type registered with registerActionTypes. On desktop it is emitted when the user clicks a notification (actionId is tap) or one of its actions, for notifications shown while a listener existed and as far as the notification server reports it. Without a listener, desktop notifications are shown without their actions.

Platform-specific

  • Windows: a click is only reported while the toast is on screen, not once it moved to the Action Center.
  • macOS: two or more actions are shown in an “Options” menu, and a click on the menu button itself reports the first action. Actions are told apart by their title.
import { onAction } from '@tauri-apps/plugin-notification';
const unlisten = await onAction((event) => {
console.log(`user performed ${event.actionId} on ${event.notification?.title}`);
});
Parameter Type Description
cb (event: ActionPerformed) => void The closure called with the performed action and the notification it refers to.

Promise<PluginListener>

A promise resolving to a listener that can be used to stop listening for the event.

2.0.0


function onNotificationReceived(cb: (notification: Options) => void): Promise<PluginListener>;

Defined in: plugins/notification/guest-js/index.ts:922

Listens to notifications that are delivered while the app is running.

Only emitted on mobile.

import { onNotificationReceived } from '@tauri-apps/plugin-notification';
const unlisten = await onNotificationReceived((notification) => {
console.log(`received notification: ${notification.title}`);
});
Parameter Type Description
cb (notification: Options) => void The closure called with the notification that was delivered.

Promise<PluginListener>

A promise resolving to a listener that can be used to stop listening for the event.

2.0.0


function pending(): Promise<PendingNotification[]>;

Defined in: plugins/notification/guest-js/index.ts:743

Retrieves the list of pending notifications.

import { pending } from '@tauri-apps/plugin-notification';
const pendingNotifications = await pending();

Promise<PendingNotification[]>

A promise resolving to the list of pending notifications.

2.0.0


function registerActionTypes(types: ActionType[]): Promise<void>;

Defined in: plugins/notification/guest-js/index.ts:726

Register actions that are performed when the user clicks on the notification.

On desktop the actions of a type become the buttons of the notifications that reference it; only their id and title are used there.

import { registerActionTypes } from '@tauri-apps/plugin-notification';
await registerActionTypes([{
id: 'tauri',
actions: [{
id: 'my-action',
title: 'Settings'
}]
}])
Parameter Type Description
types ActionType[] The action types to register.

Promise<void>

A promise indicating the success or failure of the operation.

2.0.0


function removeActive(notifications: {
id: number;
tag?: string;
}[]): Promise<void>;

Defined in: plugins/notification/guest-js/index.ts:818

Removes the active notifications with the given list of identifiers.

import { removeActive } from '@tauri-apps/plugin-notification';
await removeActive([{ id: -34234 }, { id: 23432 }, { id: 4311 }])

On desktop only notifications shown while an onAction listener existed can be removed, and only on Linux and the BSDs. Calling removeAllActive removes all such notifications.

Parameter Type Description
notifications { id: number; tag?: string; }[] The active notifications to remove, identified by their id and, on Android, their optional tag.

Promise<void>

A promise indicating the success or failure of the operation.

2.0.0


function removeAllActive(): Promise<void>;

Defined in: plugins/notification/guest-js/index.ts:837

Removes all active notifications.

import { removeAllActive } from '@tauri-apps/plugin-notification';
await removeAllActive()

Promise<void>

A promise indicating the success or failure of the operation.

2.0.0


function removeChannel(id: string): Promise<void>;

Defined in: plugins/notification/guest-js/index.ts:882

Removes the channel with the given identifier.

import { removeChannel } from '@tauri-apps/plugin-notification';
await removeChannel('new-messages');
Parameter Type Description
id string The identifier of the channel to remove.

Promise<void>

A promise indicating the success or failure of the operation.

2.0.0


function requestPermission(): Promise<NotificationPermission>;

Defined in: plugins/notification/guest-js/index.ts:670

Requests the permission to send notifications.

import { isPermissionGranted, requestPermission } from '@tauri-apps/plugin-notification';
let permissionGranted = await isPermissionGranted();
if (!permissionGranted) {
const permission = await requestPermission();
permissionGranted = permission === 'granted';
}

Promise<NotificationPermission>

A promise resolving to whether the user granted the permission or not.

2.0.0


function sendNotification(options: string | Options): void;

Defined in: plugins/notification/guest-js/index.ts:694

Sends a notification to the user.

import { isPermissionGranted, requestPermission, sendNotification } from '@tauri-apps/plugin-notification';
let permissionGranted = await isPermissionGranted();
if (!permissionGranted) {
const permission = await requestPermission();
permissionGranted = permission === 'granted';
}
if (permissionGranted) {
sendNotification('Tauri is awesome!');
sendNotification({ title: 'TAURI', body: 'Tauri is awesome!' });
}
Parameter Type Description
options string | Options The notification content, or the notification title when a string is given.

void

2.0.0

Defined in: plugins/notification/guest-js/index.ts:541

How much the notifications of a Channel interrupt the user.

It maps to the Android NotificationManager.IMPORTANCE_* constants and is only used on Android.

Enumeration Member Value Description Defined in
Default 3 The notifications are shown and make a sound. This is the value used when the channel does not define an importance. plugins/notification/guest-js/index.ts:559
High 4 The notifications are shown, make a sound and pop up as a heads-up notification. plugins/notification/guest-js/index.ts:563
Low 2 The notifications are shown without a sound. plugins/notification/guest-js/index.ts:553
Min 1 The notifications are only shown in the shade, below the fold, without a status bar icon. plugins/notification/guest-js/index.ts:549
None 0 The notifications are not shown. plugins/notification/guest-js/index.ts:545

Defined in: plugins/notification/guest-js/index.ts:190

The unit of the repeating interval used by Schedule.every.

Enumeration Member Value Description Defined in
Day "day" The notification repeats every day. plugins/notification/guest-js/index.ts:214
Hour "hour" The notification repeats every hour. plugins/notification/guest-js/index.ts:218
Minute "minute" The notification repeats every minute. plugins/notification/guest-js/index.ts:222
Month "month" The notification repeats every month. On Android a month is approximated as 30 days. plugins/notification/guest-js/index.ts:202
Second "second" The notification repeats every second. Not supported on iOS, where repeating triggers must be at least a minute apart. plugins/notification/guest-js/index.ts:228
TwoWeeks "twoWeeks" The notification repeats every two weeks. plugins/notification/guest-js/index.ts:206
Week "week" The notification repeats every week. plugins/notification/guest-js/index.ts:210
Year "year" The notification repeats every year. On Android a year is approximated as 52 weeks. plugins/notification/guest-js/index.ts:196

Defined in: plugins/notification/guest-js/index.ts:571

How much of a notification is shown on the lock screen.

It maps to the Android Notification.VISIBILITY_* constants and is only used on Android.

Enumeration Member Value Description Defined in
Private 0 The notification is shown on the lock screen with its sensitive content hidden. This is the value used when the channel does not define a visibility. plugins/notification/guest-js/index.ts:581
Public 1 The notification is shown in full on the lock screen. plugins/notification/guest-js/index.ts:585
Secret -1 The notification is not shown on the lock screen at all. plugins/notification/guest-js/index.ts:575

Defined in: plugins/notification/guest-js/index.ts:240

Defines when a scheduled notification is delivered.

Build one with the static Schedule.at, Schedule.interval and Schedule.every helpers, then pass it to the schedule option of a notification. Scheduling is only supported on mobile; desktop notifications are always shown immediately.

2.0.0

new Schedule(): Schedule;

Schedule

Property Type Description Defined in
at | { allowWhileIdle: boolean; date: Date; repeating: boolean; } | undefined Set when the notification fires at a fixed date and time. plugins/notification/guest-js/index.ts:244
every | { allowWhileIdle: boolean; count: number; interval: ScheduleEvery; } | undefined Set when the notification repeats on a fixed interval. plugins/notification/guest-js/index.ts:265
interval | { allowWhileIdle: boolean; interval: ScheduleInterval; } | undefined Set when the notification fires whenever the current date matches the given fields. plugins/notification/guest-js/index.ts:255

static at(
date: Date,
repeating?: boolean,
allowWhileIdle?: boolean
): Schedule;

Defined in: plugins/notification/guest-js/index.ts:289

Creates a schedule that fires the notification at the given date and time.

import { Schedule, sendNotification } from '@tauri-apps/plugin-notification';
const schedule = Schedule.at(new Date(Date.now() + 60 * 1000));
sendNotification({ title: 'Tauri', body: 'One minute later', schedule });
Parameter Type Default value Description
date Date undefined The date and time the notification fires at. It must be in the future.
repeating boolean false Whether the notification keeps repeating, using the duration between the moment it is scheduled and date as the interval. The interval must be at least one minute on iOS.
allowWhileIdle boolean false Whether the notification is allowed to fire while the device is in low-power idle (Doze) mode. Android only.

Schedule

A schedule that can be assigned to the schedule option of a notification.

static every(
kind: ScheduleEvery,
count: number,
allowWhileIdle?: boolean
): Schedule;

Defined in: plugins/notification/guest-js/index.ts:341

Creates a schedule that repeatedly fires the notification, once every count interval units.

import { Schedule, ScheduleEvery, sendNotification } from '@tauri-apps/plugin-notification';
const schedule = Schedule.every(ScheduleEvery.Hour, 2);
sendNotification({ title: 'Tauri', body: 'Every two hours', schedule });
Parameter Type Default value Description
kind ScheduleEvery undefined The unit of the repeating interval.
count number undefined How many interval units elapse between each notification.
allowWhileIdle boolean false Whether the notification is allowed to fire while the device is in low-power idle (Doze) mode. Android only.

Schedule

A schedule that can be assigned to the schedule option of a notification.

static interval(interval: ScheduleInterval, allowWhileIdle?: boolean): Schedule;

Defined in: plugins/notification/guest-js/index.ts:314

Creates a schedule that fires the notification whenever the current date matches every field set on the given interval.

import { Schedule, sendNotification } from '@tauri-apps/plugin-notification';
// fires every day at 9:00
const schedule = Schedule.interval({ hour: 9, minute: 0 });
sendNotification({ title: 'Tauri', body: 'Good morning', schedule });
Parameter Type Default value Description
interval ScheduleInterval undefined The date fields the current date must match for the notification to fire.
allowWhileIdle boolean false Whether the notification is allowed to fire while the device is in low-power idle (Doze) mode. Android only.

Schedule

A schedule that can be assigned to the schedule option of a notification.

Defined in: plugins/notification/guest-js/index.ts:370

A button the user can tap on a notification, belonging to an ActionType.

On Android only the identifier, the title and the input flag are used. On desktop only the identifier and title are used.

Property Type Description Defined in
destructive? boolean Whether the action is displayed as destructive, usually in red. iOS only. plugins/notification/guest-js/index.ts:390
foreground? boolean Whether the app is brought to the foreground when the action is triggered. iOS only. plugins/notification/guest-js/index.ts:386
id string The identifier of this action, reported back when the user triggers it. plugins/notification/guest-js/index.ts:374
input? boolean Whether triggering the action lets the user type a text response. plugins/notification/guest-js/index.ts:394
inputButtonTitle? string The text displayed on the button that submits the text input. iOS only. plugins/notification/guest-js/index.ts:398
inputPlaceholder? string The placeholder displayed on the empty text input field. iOS only. plugins/notification/guest-js/index.ts:402
requiresAuthentication? boolean Whether the device must be unlocked for the action to run. iOS only. plugins/notification/guest-js/index.ts:382
title string The text displayed on the action button. plugins/notification/guest-js/index.ts:378

Defined in: plugins/notification/guest-js/index.ts:527

An action the user performed on a notification.

Property Type Description Defined in
actionId string The identifier of the performed action, or tap for the notification itself. plugins/notification/guest-js/index.ts:529
inputValue string | null The text entered for an input action, on mobile. plugins/notification/guest-js/index.ts:531
notification | ActiveNotification | null The notification the action was performed on, when the platform reports it. plugins/notification/guest-js/index.ts:533

Defined in: plugins/notification/guest-js/index.ts:412

A group of Actions a notification can display, referenced by the actionTypeId option of a notification.

Register it with registerActionTypes before sending a notification that uses it. On desktop, the actions become buttons on notifications that reference this type.

Property Type Description Defined in
actions Action[] The list of associated actions plugins/notification/guest-js/index.ts:420
allowInCarPlay? boolean Whether the notification can be displayed in a CarPlay environment. iOS only. plugins/notification/guest-js/index.ts:432
customDismissAction? boolean Whether the app is notified when the user dismisses the notification. iOS only. plugins/notification/guest-js/index.ts:428
hiddenPreviewsBodyPlaceholder? string The placeholder shown instead of the notification body when previews are hidden. iOS only. plugins/notification/guest-js/index.ts:424
hiddenPreviewsShowSubtitle? boolean Whether the notification subtitle is shown even when previews are hidden. iOS only. plugins/notification/guest-js/index.ts:440
hiddenPreviewsShowTitle? boolean Whether the notification title is shown even when previews are hidden. iOS only. plugins/notification/guest-js/index.ts:436
id string The identifier of this action type plugins/notification/guest-js/index.ts:416

Defined in: plugins/notification/guest-js/index.ts:473

A notification that was delivered and is still visible in the notification center.

Returned by active, which is only supported on mobile, and by onAction on mobile and desktop. Which fields are populated depends on the platform.

Property Type Description Defined in
actionTypeId? string The identifier of the action type the notification was registered with. iOS only. plugins/notification/guest-js/index.ts:513
attachments Attachment[] The attachments of the notification. iOS only. plugins/notification/guest-js/index.ts:509
body? string The body of the notification, if it was set. plugins/notification/guest-js/index.ts:489
data Record<string, string> The platform extras attached to the notification, as string values. Android only. plugins/notification/guest-js/index.ts:501
extra Record<string, unknown> The extra payload that was stored in the notification. plugins/notification/guest-js/index.ts:505
group? string The identifier of the group the notification belongs to. Android only. plugins/notification/guest-js/index.ts:493
groupSummary boolean Whether the notification is the summary of its group. Android only. plugins/notification/guest-js/index.ts:497
id number The identifier of the notification. plugins/notification/guest-js/index.ts:477
schedule? Schedule The schedule the notification was delivered with, if it was scheduled. plugins/notification/guest-js/index.ts:517
sound? string The sound resource name of the notification. iOS only. plugins/notification/guest-js/index.ts:521
tag? string The tag the notification was posted with. Android only. plugins/notification/guest-js/index.ts:481
title? string The title of the notification, if it was set. plugins/notification/guest-js/index.ts:485

Defined in: plugins/notification/guest-js/index.ts:357

Attachment of a notification.

Property Type Description Defined in
id string Attachment identifier. plugins/notification/guest-js/index.ts:359
url string Attachment URL. Accepts the asset and file protocols. plugins/notification/guest-js/index.ts:361

Defined in: plugins/notification/guest-js/index.ts:594

A notification channel, the category users configure notification behavior on.

Notifications reference a channel through their channelId option and are not delivered when the channel does not exist. Channels are only supported on Android.

Property Type Description Defined in
description? string The user visible description of this channel. plugins/notification/guest-js/index.ts:606
id string The identifier of this channel. plugins/notification/guest-js/index.ts:598
importance? Importance How much the notifications of this channel interrupt the user. plugins/notification/guest-js/index.ts:628
lightColor? string The color of the device light, as a color string such as #ff0000. plugins/notification/guest-js/index.ts:620
lights? boolean Whether the notifications of this channel blink the device light. plugins/notification/guest-js/index.ts:616
name string The user visible name of this channel. plugins/notification/guest-js/index.ts:602
sound? string The name of the sound resource played by the notifications of this channel. The resource must be placed in the app’s res/raw folder. plugins/notification/guest-js/index.ts:612
vibration? boolean Whether the notifications of this channel vibrate the device. plugins/notification/guest-js/index.ts:624
visibility? Visibility How much of the notifications of this channel is shown on the lock screen. plugins/notification/guest-js/index.ts:632

Defined in: plugins/notification/guest-js/index.ts:25

Options to send a notification.

2.0.0

Property Type Description Defined in
actionTypeId? string Defines an action type for this notification. plugins/notification/guest-js/index.ts:62
attachments? Attachment[] Notification attachments. plugins/notification/guest-js/index.ts:111
autoCancel? boolean Automatically cancel the notification when the user clicks on it. plugins/notification/guest-js/index.ts:127
body? string Optional notification body. plugins/notification/guest-js/index.ts:44
channelId? string Identifier of the Channel that deliveres this notification. If the channel does not exist, the notification won’t fire. Make sure the channel exists with listChannels and createChannel. plugins/notification/guest-js/index.ts:36
extra? Record<string, unknown> Extra payload to store in the notification. plugins/notification/guest-js/index.ts:115
group? string Identifier used to group multiple notifications. https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent/1649872-threadidentifier plugins/notification/guest-js/index.ts:68
groupSummary? boolean Instructs the system that this notification is the summary of a group on Android. plugins/notification/guest-js/index.ts:72
icon? string Notification icon. On Android the icon must be placed in the app’s res/drawable folder. plugins/notification/guest-js/index.ts:97
iconColor? string Icon color on Android. plugins/notification/guest-js/index.ts:107
id? number The notification identifier to reference this object later. Must be a 32-bit integer. plugins/notification/guest-js/index.ts:29
inboxLines? string[] List of lines to add to the notification. Changes the notification style to inbox. Cannot be used with largeBody. Only supports up to 5 lines. plugins/notification/guest-js/index.ts:91
largeBody? string Multiline text. Changes the notification style to big text. Cannot be used with inboxLines. plugins/notification/guest-js/index.ts:54
largeIcon? string Notification large icon (Android). The icon must be placed in the app’s res/drawable folder. plugins/notification/guest-js/index.ts:103
number? number Sets the number of items this notification represents on Android. plugins/notification/guest-js/index.ts:139
ongoing? boolean If true, the notification cannot be dismissed by the user on Android. An application service must manage the dismissal of the notification. It is typically used to indicate a background task that is pending (e.g. a file download) or the user is engaged with (e.g. playing music). plugins/notification/guest-js/index.ts:123
schedule? Schedule Schedule this notification to fire on a later time or a fixed interval. plugins/notification/guest-js/index.ts:48
silent? boolean Changes the notification presentation to be silent on iOS (no badge, no sound, not listed). plugins/notification/guest-js/index.ts:131
sound? string The sound resource name or file path for the notification. Platform-specific behavior - On macOS: use system sounds (e.g., “Ping”, “Blow”) or sound files in the app bundle - On Linux: use XDG theme sounds (e.g., “message-new-instant”) or file paths - On Windows: use file paths to sound files (.wav format) - On Mobile: use resource names plugins/notification/guest-js/index.ts:83
summary? string Detail text for the notification with largeBody, inboxLines or groupSummary. plugins/notification/guest-js/index.ts:58
title string The title displayed on the notification. plugins/notification/guest-js/index.ts:40
visibility? Visibility Notification visibility. plugins/notification/guest-js/index.ts:135

Defined in: plugins/notification/guest-js/index.ts:448

A notification that was scheduled and has not been delivered yet.

Returned by pending, which is only supported on mobile.

Property Type Description Defined in
body? string The body of the notification, if it was set. plugins/notification/guest-js/index.ts:460
id number The identifier of the notification. plugins/notification/guest-js/index.ts:452
schedule Schedule The schedule that determines when the notification is delivered. plugins/notification/guest-js/index.ts:464
title? string The title of the notification, if it was set. plugins/notification/guest-js/index.ts:456

Defined in: plugins/notification/guest-js/index.ts:148

The set of date fields a scheduled notification must match to be delivered.

Fields that are not set match any value, so the notification fires on every date whose remaining components match.

Property Type Description Defined in
day? number The day of the month the notification fires on. plugins/notification/guest-js/index.ts:160
hour? number The hour of the day the notification fires on, in the 24-hour clock. plugins/notification/guest-js/index.ts:176
minute? number The minute of the hour the notification fires on. plugins/notification/guest-js/index.ts:180
month? number The month of the year the notification fires on. plugins/notification/guest-js/index.ts:156
second? number The second of the minute the notification fires on. plugins/notification/guest-js/index.ts:184
weekday? number The day of the week the notification fires on. 1 - Sunday 2 - Monday 3 - Tuesday 4 - Wednesday 5 - Thursday 6 - Friday 7 - Saturday plugins/notification/guest-js/index.ts:172
year? number The year the notification fires on. plugins/notification/guest-js/index.ts:152

type PermissionState = "granted" | "denied" | "prompt" | "prompt-with-rationale";

Defined in: @tauri-apps/api/core.d.ts:179


© 2026 Tauri Contributors. CC-BY / MIT