---
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

<Tabs>
  <TabItem label="macOS" icon="fa-brands:apple">
    
    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
    
  </TabItem>
  
  <TabItem label="Windows" icon="fa-brands:windows">
    
    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`
    
  </TabItem>
  
  <TabItem label="Linux" icon="fa-brands:linux">
    
    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
    
  </TabItem>
</Tabs>

## 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
}
```