API Reference

About This Reference

This is the complete API reference for Wails v3. It documents every public type, method, and option available in the framework.

Organisation:

  • Application - Core application APIs
  • Window - Window creation and management
  • Menu - Application, context, and system tray menus
  • Events - Event system and built-in events
  • Dialogs - File and message dialogs
  • Frontend Runtime - Frontend runtime APIs
  • CLI - Command-line interface

API Conventions

Go API Conventions - For developers new to Go

Naming

  • Types: PascalCase (e.g., WebviewWindow)
  • Methods: PascalCase (e.g., SetTitle())
  • Options: PascalCase structs (e.g., WindowOptions)
  • Constants: PascalCase (e.g., WindowStartStateMaximised)

Error Handling

Most methods that can fail return error as the last return value. app.Run() blocks until the application exits and returns any startup error:

if err := app.Run(); err != nil {
    log.Fatal(err)
}

Window construction does not return an error — app.Window.New() returns *WebviewWindow directly.

Context

Service lifecycle methods receive a context.Context:

func (s *MyService) ServiceStartup(ctx context.Context, options application.ServiceOptions) error {
    // ctx is cancelled when the application is shutting down.
    return nil
}

The application’s lifetime context is available via app.Context(). There is no RunWithContext — call app.Run().

Options Pattern

Configuration uses option structs:

app := application.New(application.Options{
    Name: "My App",
    Description: "A demo application",
    Services: []application.Service{
        application.NewService(&MyService{}),
    },
})

JavaScript API Conventions

Naming

  • Functions: camelCase (e.g., setTitle())
  • Constants: SCREAMING_SNAKE_CASE (e.g., WINDOW_EVENT_FOCUS)

Async by Default

All Go method calls return Promises:

// Async/await (recommended)
const result = await MyService.DoSomething()

// Promise chain
MyService.DoSomething()
    .then(result => console.log(result))
    .catch(error => console.error(error))

Error Handling

Go errors become JavaScript exceptions:

try {
    await MyService.MightFail()
} catch (error) {
    console.error('Go error:', error)
}

Type Safety

TypeScript definitions are auto-generated:

// Fully typed
import { Greet } from './bindings/GreetService'

const message: string = await Greet("World")

Package Structure

github.com/wailsapp/wails/v3/pkg/
├── application/          # Core application package
│   ├── application.go    # App type
│   ├── webview_window.go # Window management
│   ├── menu.go           # Menu types
│   ├── event_manager.go  # Event system
│   └── dialogs.go        # Dialog APIs
├── events/               # Event constants
└── services/             # Built-in services
    ├── dock/             # macOS dock (includes badge support)
    ├── fileserver/       # File-server service
    ├── kvstore/          # Key/value store
    ├── log/              # Structured logging service
    ├── notifications/    # Notifications service
    └── sqlite/           # SQLite service

Import Paths

Go

import (
    "github.com/wailsapp/wails/v3/pkg/application"
    "github.com/wailsapp/wails/v3/pkg/events"
)

JavaScript

// Auto-generated bindings
import { MyMethod } from './bindings/MyService'

// Runtime APIs
import { Events, Window } from '@wailsio/runtime'

Type Reference

Common Types

// Application
type App struct { /* ... */ }
type Options struct { /* ... */ }

// Window
type WebviewWindow struct { /* ... */ } // implements the Window interface
type WebviewWindowOptions struct { /* ... */ }

// Menu
type Menu struct { /* ... */ }
type MenuItem struct { /* ... */ }

// Events — there is no generic Event type; events are typed by source.
type ApplicationEvent struct { /* ... */ }
type WindowEvent struct { /* ... */ }
type CustomEvent struct { /* ... */ }
type EventListener struct { /* ... */ }

// Dialogs
type OpenFileDialogOptions struct { /* ... */ }
type SaveFileDialogOptions struct { /* ... */ }

Platform Differences

Some APIs behave differently on different platforms:

Feature Windows macOS Linux
Application Menu Window menu bar Global menu bar Window menu bar
System Tray Notification area Menu bar System tray
Dock N/A ✅ Available N/A
File dialogs Native Native Native (GTK)
Transparency ✅ Full ✅ Full ⚠️ Limited

Platform-specific behaviour is documented in each API section.

Versioning

Wails v3 follows semantic versioning:

  • Major (v3.x.x): Breaking changes
  • Minor (v3.x.x): New features, backwards-compatible
  • Patch (v3.x.x): Bug fixes, backwards-compatible

Current status: Beta (API stable, refinements ongoing)

Deprecation Policy

When APIs are deprecated:

  1. Marked in docs with deprecation notice
  2. Alternative provided with migration guide
  3. Maintained for 1 major version before removal
  4. Compiler warnings (where possible)

API Stability

Stable APIs ✅

These APIs are stable and safe for production use:

  • Core application APIs
  • Window management
  • Menu system
  • Event system
  • File dialogs
  • Service bindings

Unstable APIs ⚠️

These APIs may change before final release:

  • Some advanced window options
  • Platform-specific features
  • Experimental features

Unstable APIs are marked in documentation.

Getting Help

API Questions

  1. Check this reference - Complete API documentation
  2. Check examples - GitHub examples
  3. Search Discord - Discord server
  4. Ask the community - Discord #help channel

Reporting API Issues

Found a bug or inconsistency?

  1. Check existing issues - GitHub issues
  2. Create detailed report - Include code, error, platform
  3. Provide reproduction - Minimal example that demonstrates issue
  • Tutorials - Learn by building real applications
  • Guides - Task-oriented guides for common scenarios
  • Features - Feature-by-feature documentation
  • Examples - Working code examples on GitHub

Browse the API: Use the navigation on the left to explore specific APIs.

Edit page

Last updated: