API Reference

Complete API documentation for Wails v3

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

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

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

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

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

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

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.