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:

window, err := app.Window.New()
if err != nil {
    log.Fatal(err)
}

Context

Methods that may block or need cancellation accept context.Context:

err := app.RunWithContext(ctx)

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    # Application type
│   ├── webview_window.go # Window management
│   ├── menu.go           # Menu types
│   ├── events.go         # Event system
│   └── dialogs.go        # dialog APIs
├── events/               # Event constants
└── services/             # Built-in services
    ├── badge/            # Badge 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 Application struct { /* ... */ }
type Options struct { /* ... */ }

// Window
type WebviewWindow struct { /* ... */ }
type WebviewWindowOptions struct { /* ... */ }

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

// Events
type Event struct { /* ... */ }
type EventListener func(*Event)

// Dialogs
type OpenDialogOptions struct { /* ... */ }
type SaveDialogOptions 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.