Badges

Introduction

Wails provides a cross-platform badge service for desktop applications. This service allows you to display badges on your application tile or dock icon, which is useful for indicating unread messages, notifications, or other status information.

Basic Usage

Creating the Service

First, initialize the badge service:

import "github.com/wailsapp/wails/v3/pkg/application"
import "github.com/wailsapp/wails/v3/pkg/services/badge"

// Create a new badge service
badgeService := badge.New()

// Register the service with the application
app := application.New(application.Options{
    Services: []application.Service{
        application.NewService(badgeService),
    },
})

Creating the Service with Custom Options (Windows Only)

On Windows, you can customize the badge appearance with various options:

import "github.com/wailsapp/wails/v3/pkg/application"
import "github.com/wailsapp/wails/v3/pkg/services/badge"
import "image/color"

// Create a badge service with custom options
options := badge.Options{
    TextColour:       color.RGBA{255, 255, 255, 255}, // White text
    BackgroundColour: color.RGBA{0, 0, 255, 255},     // Blue background
    FontName:         "consolab.ttf",                 // Bold Consolas font
    FontSize:         20,                             // Font size for single character
    SmallFontSize:    14,                             // Font size for multiple characters
}

badgeService := badge.NewWithOptions(options)

// Register the service with the application
app := application.New(application.Options{
    Services: []application.Service{
        application.NewService(badgeService),
    },
})

Badge Operations

Setting a Badge

Set a badge on the application tile/dock icon:

// Set a default badge
badgeService.SetBadge("")

// Set a numeric badge
badgeService.SetBadge("3")

// Set a text badge
badgeService.SetBadge("New")

Setting a Custom Badge

Set a badge on the application tile/dock icon with one-off options applied:

Go

options := badge.Options{
    BackgroundColour: color.RGBA{0, 255, 255, 255},
    FontName: "arialb.ttf", // System font
    FontSize: 16,
    SmallFontSize: 10,
    TextColour: color.RGBA{0, 0, 0, 255},
}

// Set a default badge
badgeService.SetCustomBadge("", options)

// Set a numeric badge
badgeService.SetCustomBadge("3", options)

// Set a text badge
badgeService.SetCustomBadge("New", options)

Removing a Badge

Remove the badge from the application icon:

badgeService.RemoveBadge()

Platform Considerations

macOS

On macOS, badges:

• Are displayed directly on the dock icon
• Support text values
• Automatically handle dark/light mode appearance
• Use the standard macOS dock badge styling
• Automatically handle label overflow
• Do not support customization options (any options passed to NewWithOptions will be ignored)
• Will display ”●” as the default badge if an empty label is provided

Windows

On Windows, badges:

• Are displayed as an overlay icon in the taskbar
• Support text values
• Allow customization of colors, font, and font sizes
• Adapt to Windows theme settings
• Require the application to have a window
• Use smaller font size automatically for badges with multiple characters
• Do not handle label overflow
• Support the following customization options:
  • TextColour: Text color (default: white)
  • BackgroundColour: Badge background color (default: red)
  • FontName: Font file name (default: “segoeuib.ttf”)
  • FontSize: Font size for single character (default: 18)
  • SmallFontSize: Font size for multiple characters (default: 14)

Linux

On Linux:

• Badge functionality is not available

Best Practices

1. Use badges sparingly:

   • Too many badge updates can distract users
   • Reserve badges for important notifications

2. Keep badge text short:

   • Numeric badges are most effective
   • On macOS, text badges should be brief

3. For Windows customization:

   • Ensure high contrast between text and background colors
   • Test with different text lengths as font size decreases with length
   • Use common system fonts to ensure availability

API Reference

Service Management

Method	Description
New()	Creates a new badge service with default options
NewWithOptions(options Options)	Creates a new badge service with custom options (Windows only, options are ignored on macOS)

Badge Operations

Method	Description
SetBadge(label string) error	Sets a badge with the specified label
SetCustomBadge(label string, options Options) error	Sets a badge with the specified label and custom styling options (Windows only)
RemoveBadge() error	Removes the badge from the application icon

Structs and Types

// Options for customizing badge appearance (Windows only)
type Options struct {
    TextColour       color.RGBA  // Color of the badge text
    BackgroundColour color.RGBA  // Color of the badge background
    FontName         string      // Font file name (e.g., "segoeuib.ttf")
    FontSize         int         // Font size for single character
    SmallFontSize    int         // Font size for multiple characters
}