Notifications

Send native system notifications with permission handling and user preference support in Local.ts.

Local.ts includes native notification support with permission handling and user preferences.

Thus, you can send system notifications that respect user settings and platform requirements.

Understanding Notifications

Notifications in Local.ts have two layers of control:

System permissions — The OS must grant notification access
User preferences — Users can disable notifications in Settings

The notification helpers handle both automatically, so you can focus on when and what to notify.

Sending Notifications

Basic Notification

Use notify() to send a notification that respects user preferences:

import { notify } from "@/lib/tauri/notifications/send";
import { useSettings } from "@/stores/settings";

async function sendNotification() {
  const settings = useSettings.getState().settings;
  if (!settings) return;

  const sent = await notify({
    title: "Task Complete",
    body: "Your export has finished successfully.",
  }, settings);

  if (sent) {
    console.log("Notification delivered");
  } else {
    console.log("Notification blocked by settings or permissions");
  }
}

Critical Notifications

For urgent alerts that should bypass user preferences (but still require system permission):

import { notifyForced } from "@/lib/tauri/notifications/send";

async function sendCriticalAlert() {
  await notifyForced({
    title: "Critical Error",
    body: "Your data could not be saved. Please try again.",
  });
}

Use notifyForced sparingly. Overusing it will frustrate users who have disabled notifications.

Notification Options

Both notify and notifyForced accept the same options:

interface NotificationOptions {
  title: string;      // Required: notification title
  body?: string;      // Optional: notification body text
  icon?: string;      // Optional: path to icon file
}

Example with all options:

await notify({
  title: "New Message",
  body: "You have a new message from Alice",
  icon: "icons/message.png",
}, settings);

You can change this NotificationOptions interface however you want and modify the notify and notifyForced helpers to add more fields according to the Tauri notification plugin options.

Checking Permissions

Before showing notifications, ensure you have permission:

import {
  isPermissionGranted,
  requestPermission,
} from "@tauri-apps/plugin-notification";

// Check current permission status
const hasPermission = await isPermissionGranted();

// Request permission (shows system prompt if needed)
const granted = await requestPermission();
if (granted) {
  console.log("Notifications enabled");
}

You can use the following convenient helper to ensure notification permission is granted (it checks and requests if needed):

// src/lib/tauri/notifications/permissions.ts
import {
  isPermissionGranted,
  requestPermission,
} from "@tauri-apps/plugin-notification";

/**
 * Ensure notification permission is granted.
 * Requests permission if not already granted.
 */
export async function ensureNotificationPermission(): Promise<NotificationPermission> {
  const granted = await isPermissionGranted();
  if (granted) {
    return "granted";
  }
  return await requestPermission();
}

User Preferences

The Settings page includes a notification toggle. When users enable notifications, permission is automatically requested:

import { requestPermission } from "@tauri-apps/plugin-notification";

// simplified implementation
const handleNotificationChange = async (enabled: boolean) => {
  if (enabled) {
    const granted = await requestPermission();
    if (granted !== "granted") {
      // Permission denied, don't enable notifications
      return;
    }
  }
};

How It Works

The notify function implements this logic:

export async function notify(
  options: NotificationOptions,
  settings: Settings
): Promise<boolean> {
  // 1. Check user preferences
  if (!settings.enableNotifications) {
    return false;
  }

  // 2. Ensure system permission
  const granted = await ensureNotificationPermission();
  if (granted !== "granted") {
    return false;
  }

  // 3. Send the notification
  sendNotification({
    title: options.title,
    body: options.body,
    icon: options.icon,
  });

  return true;
}

Removing Notifications

If you don't need notification functionality:

Remove the plugin from src-tauri/src/lib.rs:

- .plugin(tauri_plugin_notification::init())

Remove the dependency from src-tauri/Cargo.toml:
```
- tauri-plugin-notification = "2"
```
Remove permissions from src-tauri/capabilities/default.json:
```
- "notification:default"
```

Remove the npm package:

pnpm remove @tauri-apps/plugin-notification

Delete the notifications module — Remove src/lib/tauri/notifications/

Edit on GitHub

Last updated on

Notifications

On this page