--- title: Notifications description: Display native system notifications with action buttons and text input sidebar: order: 1 --- import { Tabs, TabItem } from "@astrojs/starlight/components"; ## Introduction Wails provides a comprehensive cross-platform notification system for desktop applications. This service allows you to display native system notifications, with support for interactive elements like action buttons and text input fields. ## Basic Usage ### Creating the Service First, initialize the notifications service: ```go import "github.com/wailsapp/wails/v3/pkg/application" import "github.com/wailsapp/wails/v3/pkg/services/notifications" // Create a new notification service notifier := notifications.New() //Register the service with the application app := application.New(application.Options{ Services: []application.Service{ application.NewService(notifier), }, }) ``` ## Notification Authorization Notifications on macOS require user authorization. Request and check authorization: ```go authorized, err := notifier.CheckNotificationAuthorization() if err != nil { // Handle authorization error } if authorized { // Send notifications } else { // Request authorization authorized, err = notifier.RequestNotificationAuthorization() } ``` On Windows and Linux this always returns `true`. ## Notification Types ### Basic Notifications Send a basic notification with a unique id, title, optional subtitle (macOS and Linux), and body text to users: ```go notifier.SendNotification(notifications.NotificationOptions{ ID: "unique-id", Title: "New Calendar Invite", Subtitle: "From: Jane Doe", // Optional Body: "Tap to view the event", }) ``` ### Interactive Notifications Send a notification with action buttons and text inputs. These notifications require a notification category to be resgistered first: ```go // Define a unique category id categoryID := "unique-category-id" // Define a category with actions category := notifications.NotificationCategory{ ID: categoryID, Actions: []notifications.NotificationAction{ { ID: "OPEN", Title: "Open", }, { ID: "ARCHIVE", Title: "Archive", Destructive: true, /* macOS-specific */ }, }, HasReplyField: true, ReplyPlaceholder: "message...", ReplyButtonTitle: "Reply", } // Register the category notifier.RegisterNotificationCategory(category) // Send an interactive notification with the actions registered in the provided category notifier.SendNotificationWithActions(notifications.NotificationOptions{ ID: "unique-id", Title: "New Message", Subtitle: "From: Jane Doe", Body: "Are you able to make it?", CategoryID: categoryID, }) ``` ## Notification Responses Process user interactions with notifications: ```go notifier.OnNotificationResponse(func(result notifications.NotificationResult) { response := result.Response fmt.Printf("Notification %s was actioned with: %s\n", response.ID, response.ActionIdentifier) if response.ActionIdentifier == "TEXT_REPLY" { fmt.Printf("User replied: %s\n", response.UserText) } if data, ok := response.UserInfo["sender"].(string); ok { fmt.Printf("Original sender: %s\n", data) } // Emit an event to the frontend app.Event.Emit("notification", result.Response) }) ``` ## Notification Customisation ### Custom Metadata Basic and interactive notifications can include custom data: ```go notifier.SendNotification(notifications.NotificationOptions{ ID: "unique-id", Title: "New Calendar Invite", Subtitle: "From: Jane Doe", // Optional Body: "Tap to view the event", Data: map[string]interface{}{ "sender": "jane.doe@example.com", "timestamp": "2025-03-10T15:30:00Z", } }) ``` ## Platform Considerations On macOS, notifications: - Require user authorization - Require the app to be notorized for distribution - Use system-standard notification appearances - Support `subtitle` - Support user text input - Support the `Destructive` action option - Automatically handle dark/light mode On Windows, notifications: - Use Windows system toast styles - Adapt to Windows theme settings - Support user text input - Support high DPI displays - Do not support `subtitle` On Linux, dialog behaviour depends on the desktop environment: - Use native notifications when available - Follow desktop environment theme - Position according to desktop environment rules - Support `subtitle` - Do not support user text input ## Best Practices 1. Check and request for authorization: - macOS requires user authorization 2. Provide clear and concise notifications: - Use descriptive titles, subtitles, text, and action titles 3. Handle dialog responses appropriately: - Check for errors in notification responses - Provide feedback for user actions 4. Consider platform conventions: - Follow platform-specific notification patterns - Respect system settings ## Examples Explore this example: - [Notifications](/examples/notifications) ## API Reference ### Service Management | Method | Description | |--------------------------------------------|-------------------------------------------------------| | `New()` | Creates a new notifications service | ### Notification Authorization | Method | Description | |----------------------------------------------|------------------------------------------------------------| | `RequestNotificationAuthorization()` | Requests permission to display notifications (macOS) | | `CheckNotificationAuthorization()` | Checks current notification authorization status (macOS) | ### Sending Notifications | Method | Description | |------------------------------------------------------------|---------------------------------------------------| | `SendNotification(options NotificationOptions)` | Sends a basic notification | | `SendNotificationWithActions(options NotificationOptions)` | Sends an interactive notification with actions | ### Notification Categories | Method | Description | |---------------------------------------------------------------|---------------------------------------------------| | `RegisterNotificationCategory(category NotificationCategory)` | Registers a reusable notification category | | `RemoveNotificationCategory(categoryID string)` | Removes a previously registered category | ### Managing Notifications | Method | Description | |-------------------------------------------------|---------------------------------------------------------------------| | `RemoveAllPendingNotifications()` | Removes all pending notifications (macOS and Linux only) | | `RemovePendingNotification(identifier string)` | Removes a specific pending notification (macOS and Linux only) | | `RemoveAllDeliveredNotifications()` | Removes all delivered notifications (macOS and Linux only) | | `RemoveDeliveredNotification(identifier string)`| Removes a specific delivered notification (macOS and Linux only) | | `RemoveNotification(identifier string)` | Removes a notification (Linux-specific) | ### Event Handling | Method | Description | |--------------------------------------------------------------------|-------------------------------------------------| | `OnNotificationResponse(callback func(result NotificationResult))` | Registers a callback for notification responses | ### Structs and Types #### NotificationOptions ```go type NotificationOptions struct { ID string // Unique identifier for the notification Title string // Main notification title Subtitle string // Subtitle text (macOS and Linux only) Body string // Main notification content CategoryID string // Category identifier for interactive notifications Data map[string]interface{} // Custom data to associate with the notification } ``` #### NotificationCategory ```go type NotificationCategory struct { ID string // Unique identifier for the category Actions []NotificationAction // Button actions for the notification HasReplyField bool // Whether to include a text input field ReplyPlaceholder string // Placeholder text for the input field ReplyButtonTitle string // Text for the reply button } ``` #### NotificationAction ```go type NotificationAction struct { ID string // Unique identifier for the action Title string // Button text Destructive bool // Whether the action is destructive (macOS-specific) } ``` #### NotificationResponse ```go type NotificationResponse struct { ID string // Notification identifier ActionIdentifier string // Action that was triggered CategoryID string // Category of the notification Title string // Title of the notification Subtitle string // Subtitle of the notification Body string // Body text of the notification UserText string // Text entered by the user UserInfo map[string]interface{} // Custom data from the notification } ``` #### NotificationResult ```go type NotificationResult struct { Response NotificationResponse // Response data Error error // Any error that occurred } ```