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

Go

// 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 { /* ... */ }

TypeScript

// Window runtime
interface WindowOptions {
    title?: string
    width?: number
    height?: number
    // ...
}

// Events
type EventCallback = (data: any) => void

// Bindings (auto-generated)
export function MyMethod(arg: string): Promise<string>

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: Alpha (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

Related Documentation

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