# How to Set Up Alerts in PI Desktop: Toast and Notification Center Implementation

> Learn how to set up alerts in PI Desktop using toast and Notification Center. Implement real-time notifications from JavaScript/TypeScript plugins and core code.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-12

---

**PI Desktop provides two built-in alert mechanisms—transient toast messages via `pi.ui.showToast()` and persistent notifications via `pi.api.notify()`—both accessible from JavaScript/TypeScript plugins and core application code.**

The alerting architecture in the vastsa/PI-Desktop repository enables both ephemeral user feedback and durable notification tracking. Whether you are building a plugin or modifying core functionality, you can leverage these APIs to communicate status updates, errors, and task completions.

## Toast Alerts for Transient User Feedback

Toast alerts deliver short, transient messages that appear at the top-center of the PI Desktop UI. These are ideal for immediate feedback that does not require persistent storage.

### Using the UI API from Plugins

Plugins access toast functionality through the SDK's UI module. The `pi.ui.showToast()` method routes requests through the Electron IPC bridge defined in [`apps/desktop/electron/main/plugin-runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron/main/plugin-runtime.ts), which forwards the call to the main process store.

The underlying store implementation in [`apps/desktop/src/stores/app-store.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/stores/app-store.ts) maintains the `showToast` method, which inserts toast entries into a global queue managed by the `ToastHost` component.

### Toast Configuration and Accessibility

The toast API accepts a message string and an optional options object:

- **`variant`**: Controls visual styling and ARIA roles (`"info"`, `"success"`, `"warning"`, `"error"`)
- **`duration`**: Visibility time in milliseconds (defaults to 4000ms for normal messages, 8000ms for errors)

The `Toast` component in [`apps/desktop/src/components/Toast.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/Toast.tsx) renders each toast with `role="status"` for informational variants and `role="alert"` for error or warning variants, ensuring proper screen-reader announcements via `aria-live="assertive"` regions.

```typescript
// Plugin toast implementation
import pi from '@pi/desktop/sdk';

// Informational toast (4 second default)
await pi.ui.showToast('Your notes have been saved.', { variant: 'info' });

// Warning toast with custom duration
await pi.ui.showToast('Low disk space – consider cleaning up.', {
  variant: 'warning',
  duration: 8000,
});

// Error toast (appears as ARIA alert, 8 second default)
await pi.ui.showToast('Failed to connect to the model server.', {
  variant: 'error',
});

```

## Notification Center Alerts for Persistent Storage

For alerts that users must acknowledge or reference later, PI Desktop provides a persistent notification system accessible via the bell-icon panel.

### Runtime API Implementation

Persistent notifications use the `pi.api.notify()` method (or runtime-generated events) handled by the [`plugin-runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/plugin-runtime.ts) IPC bridge. The [`App.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/App.tsx) component subscribes to notification changes via `api.onNotificationChanged`, ensuring real-time UI updates when new notifications arrive.

The notification state resides in [`apps/desktop/src/stores/app-store.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/stores/app-store.ts), which maintains a `notifications` array supporting read/unread tracking, filtering, and detailed view activation.

### Notification Payload Structure

Notifications require a structured payload containing:

- **`id`**: Unique identifier for the notification
- **`kind`**: Event categorization (e.g., `"task.failed"`, `"task.completed"`)
- **`sessionId`** and **`sessionTitle`**: Contextual task information
- **`createdAt`**: ISO timestamp
- **`readAt`**: Nullable timestamp for read status
- **`errorCode`**: Optional error classification

The `NotificationCenter` component in [`apps/desktop/src/components/NotificationCenter.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/NotificationCenter.tsx) renders these with appropriate ARIA roles—`role="alert"` for failures and `role="status"` for informational notifications.

```typescript
// Core application notification creation
import { api } from './lib/api';

const payload = {
  id: 'task-1234',
  kind: 'task.failed',
  sessionId: 'session-42',
  sessionTitle: 'Summarize document',
  createdAt: new Date().toISOString(),
  errorCode: 'E401',
};

api.notify(payload);

```

## Internal Alert Routing Architecture

Both alert types traverse through specific pathways while maintaining a single source of truth in the application store.

### Toast Routing Flow

1. **Plugin Call**: `pi.ui.showToast()` → [`plugin-runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/plugin-runtime.ts) (`"ui.showToast"` case)
2. **IPC Bridge**: Main process receives the event
3. **Store Update**: [`apps/desktop/src/stores/app-store.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/stores/app-store.ts) `showToast` method enqueues the message
4. **UI Render**: `ToastHost` component animates and displays the toast, auto-dismissing after the configured duration

### Notification Routing Flow

1. **Creation**: `pi.api.notify()` or backend event → [`plugin-runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/plugin-runtime.ts) (`"notification"` case)
2. **State Management**: Store updates the `notifications` array in [`app-store.ts`](https://github.com/vastsa/PI-Desktop/blob/main/app-store.ts)
3. **UI Subscription**: [`App.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/App.tsx) receives subscription update via `api.onNotificationChanged`
4. **Render**: [`NotificationCenter.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/NotificationCenter.tsx) displays the item in the bell-icon panel with read/unread indicators

## Key Implementation Files

The following files define the complete alerting stack in PI Desktop:

- **[`apps/desktop/src/stores/app-store.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/stores/app-store.ts)** – Contains `showToast` method and `notifications` array state management
- **[`apps/desktop/src/components/Toast.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/Toast.tsx)** – Renders toast UI with ARIA role assignment (`role="status"` or `role="alert"`)
- **[`apps/desktop/src/components/NotificationCenter.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/NotificationCenter.tsx)** – Implements the bell-icon panel with filtering, read tracking, and activation handlers
- **[`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts)** – Exposes `pi.ui.showToast` to plugin developers
- **[`apps/desktop/electron/main/plugin-runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron/main/plugin-runtime.ts)** – Bridges plugin API calls to the main process via IPC
- **[`apps/desktop/src/App.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/App.tsx)** – Subscribes to `api.onNotificationChanged` for real-time notification updates

## Summary

- **PI Desktop offers two distinct alert mechanisms**: transient toast messages for immediate feedback and persistent notification center alerts for trackable events.
- **Toast alerts** use `pi.ui.showToast()` with configurable variants (`info`, `success`, `warning`, `error`) and durations, defaulting to 4 seconds (8 seconds for errors).
- **Persistent notifications** use `pi.api.notify()` with structured payloads including `id`, `kind`, `sessionId`, and timestamps, stored in [`apps/desktop/src/stores/app-store.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/stores/app-store.ts).
- **Both systems route through** [`apps/desktop/electron/main/plugin-runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron/main/plugin-runtime.ts) over Electron IPC, ensuring secure communication between plugin sandbox and main process.
- **Accessibility is built-in**: Toasts and notifications use appropriate ARIA roles (`status` for info, `alert` for errors) and live regions for screen-reader support.

## Frequently Asked Questions

### How do I show a temporary alert from a PI Desktop plugin?

Import the SDK and call `pi.ui.showToast()` with your message and variant. The method is exposed through [`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts) and routes through the Electron IPC bridge to display the toast at the top-center of the UI.

### What is the difference between toast alerts and notification center alerts in PI Desktop?

Toast alerts are transient messages that auto-dismiss after 4–8 seconds and do not persist in the UI, implemented in [`apps/desktop/src/components/Toast.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/Toast.tsx). Notification center alerts are durable entries stored in [`apps/desktop/src/stores/app-store.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/stores/app-store.ts) that appear in the bell-icon panel and support read/unread tracking until explicitly dismissed.

### How long do toast alerts remain visible in PI Desktop?

Default duration is 4000 milliseconds for informational and success toasts, and 8000 milliseconds for error and warning variants. You can override this by passing a `duration` value (in milliseconds) to the `pi.ui.showToast()` options object.

### Where are notification states stored in PI Desktop?

Notification states persist in the MobX-based application store defined in [`apps/desktop/src/stores/app-store.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/stores/app-store.ts), specifically within the `notifications` array. This store handles read/unread status, filtering, and subscription updates consumed by [`apps/desktop/src/components/NotificationCenter.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/components/NotificationCenter.tsx).