Window API

Overview

The Window API provides methods to control window appearance, behaviour, and lifecycle. Access through window instances or the app.Window manager.

Window is an interface satisfied by *application.WebviewWindow; method signatures below are on *WebviewWindow. Many mutators return Window to allow chaining — the return values are documented per method.

Common operations:

Create and show windows
Control size, position, and state
Handle window events
Manage window content
Configure appearance and behaviour

Visibility

Show()

Shows the window. If the window was hidden, it becomes visible. Returns the receiver for chaining.

func (w *WebviewWindow) Show() Window

Example:

window := app.Window.New()
window.Show()

Hide()

Hides the window without closing it. The window remains in memory and can be shown again. Returns the receiver for chaining.

func (w *WebviewWindow) Hide() Window

Example:

// Hide window temporarily
window.Hide()

// Show it again later
window.Show()

Use cases:

System tray applications that hide to tray
Wizard flows where windows are reused
Temporary hiding during operations

Close()

Closes the window. This triggers the WindowClosing event.

func (w *WebviewWindow) Close()

Example:

window.Close()

Note: If a registered hook calls event.Cancel(), the close will be prevented.

Window Properties

SetTitle()

Sets the window title bar text. Returns the receiver for chaining.

func (w *WebviewWindow) SetTitle(title string) Window

Parameters:

title - The new window title

Example:

window.SetTitle("My Application - Document.txt")

Name()

Returns the window’s unique name identifier.

func (w *WebviewWindow) Name() string

Example:

name := window.Name()
fmt.Println("Window name:", name)

// Retrieve window by name later
if w, ok := app.Window.GetByName(name); ok {
    w.Focus()
}

Size and Position

SetSize()

Sets the window dimensions in pixels. Returns the receiver for chaining.

func (w *WebviewWindow) SetSize(width, height int) Window

Parameters:

width - Window width in pixels
height - Window height in pixels

Example:

window.SetSize(1024, 768)

Size()

Returns the current window dimensions.

func (w *WebviewWindow) Size() (width, height int)

Example:

width, height := window.Size()
fmt.Printf("Window is %dx%d\n", width, height)

SetMinSize() / SetMaxSize()

Sets minimum and maximum window dimensions. Both return the receiver for chaining.

func (w *WebviewWindow) SetMinSize(width, height int) Window
func (w *WebviewWindow) SetMaxSize(width, height int) Window

Example:

// Prevent window from being too small
window.SetMinSize(800, 600)

// Prevent window from being too large
window.SetMaxSize(1920, 1080)

SetPosition()

Sets the window position relative to the top-left corner of the screen.

func (w *WebviewWindow) SetPosition(x, y int)

Parameters:

x - Horizontal position in pixels
y - Vertical position in pixels

Example:

// Position window at top-left
window.SetPosition(0, 0)

// Position window 100px from top-left
window.SetPosition(100, 100)

Position()

Returns the current window position.

func (w *WebviewWindow) Position() (x, y int)

Example:

x, y := window.Position()
fmt.Printf("Window is at (%d, %d)\n", x, y)

Center()

Centers the window on the screen.

func (w *WebviewWindow) Center()

Example:

window := app.Window.New()
window.Center()
window.Show()

Note: Centres on the primary monitor. For multi-monitor setups, see the screen APIs.

Focus()

Brings the window to the front and gives it keyboard focus.

func (w *WebviewWindow) Focus()

Example:

// Bring window to front
window.Focus()

Window State

Minimise() / UnMinimise()

Minimises the window to the taskbar/dock or restores it. Minimise() returns the receiver for chaining; UnMinimise() returns nothing.

func (w *WebviewWindow) Minimise() Window
func (w *WebviewWindow) UnMinimise()

Example:

// Minimise window
window.Minimise()

// Restore from minimised state
window.UnMinimise()

Maximise() / UnMaximise()

Maximises the window to fill the screen or restores it to its previous size. Maximise() returns the receiver for chaining; UnMaximise() returns nothing.

func (w *WebviewWindow) Maximise() Window
func (w *WebviewWindow) UnMaximise()

Example:

// Maximise window
window.Maximise()

// Restore to previous size
window.UnMaximise()

Fullscreen() / UnFullscreen() / ToggleFullscreen()

Enters or exits fullscreen mode. Fullscreen() returns the receiver for chaining.

func (w *WebviewWindow) Fullscreen() Window
func (w *WebviewWindow) UnFullscreen()
func (w *WebviewWindow) ToggleFullscreen()

Example:

// Enter fullscreen
window.Fullscreen()

// Exit fullscreen
window.UnFullscreen()

// Or toggle
window.ToggleFullscreen()

There is no SetFullscreen(bool) method.

IsMinimised() / IsMaximised() / IsFullscreen()

Checks the current window state.

func (w *WebviewWindow) IsMinimised() bool
func (w *WebviewWindow) IsMaximised() bool
func (w *WebviewWindow) IsFullscreen() bool

Example:

if window.IsMinimised() {
    window.UnMinimise()
}

if window.IsMaximised() {
    fmt.Println("Window is maximised")
}

if window.IsFullscreen() {
    window.UnFullscreen()
}

Window Content

SetURL()

Navigates to a specific URL within the window. Returns the receiver for chaining.

func (w *WebviewWindow) SetURL(url string) Window

Parameters:

url - URL to navigate to (can be http://wails.localhost/ for embedded assets)

Example:

// Navigate to embedded page
window.SetURL("http://wails.localhost/settings.html")

// Navigate to external URL (if allowed)
window.SetURL("https://wails.io")

SetHTML()

Sets the window content directly from an HTML string. Returns the receiver for chaining.

func (w *WebviewWindow) SetHTML(html string) Window

Parameters:

html - HTML content to display

Example:

html := `
<!DOCTYPE html>
<html>
<head><title>Dynamic Content</title></head>
<body>
    <h1>Hello from Go!</h1>
    <p>This content was generated dynamically.</p>
</body>
</html>
`
window.SetHTML(html)

Use cases:

Dynamic content generation
Simple windows without a frontend build process
Error pages or splash screens

Reload()

Reloads the current window content.

func (w *WebviewWindow) Reload()

Example:

// Reload current page
window.Reload()

Note: Useful during development or when content needs refreshing.

Window Events

Wails provides two methods for handling window events:

OnWindowEvent() - Listen to window events (cannot prevent them).
RegisterHook() - Hook into window events (can prevent them by calling event.Cancel()).

OnWindowEvent()

Registers a callback for window events. Returns an unsubscribe function.

func (w *WebviewWindow) OnWindowEvent(
    eventType events.WindowEventType,
    callback func(event *WindowEvent),
) func()

Example:

import "github.com/wailsapp/wails/v3/pkg/events"

// Listen for window focus
window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window gained focus")
})

// Listen for window lost focus
window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window lost focus")
})

// Listen for window resize
window.OnWindowEvent(events.Common.WindowDidResize, func(e *application.WindowEvent) {
    app.Logger.Info("Window resized")
})

Common Window Events:

events.Common.WindowClosing - Window is about to close
events.Common.WindowFocus - Window gained focus
events.Common.WindowLostFocus - Window lost focus
events.Common.WindowDidMove - Window moved
events.Common.WindowDidResize - Window resized
events.Common.WindowMinimise - Window minimised
events.Common.WindowMaximise - Window maximised
events.Common.WindowFullscreen - Window entered fullscreen
events.Common.WindowRuntimeReady - In-window runtime initialised

RegisterHook()

Registers a hook for window events. Hooks run before listeners and can prevent the event by calling event.Cancel(). Returns an unsubscribe function.

func (w *WebviewWindow) RegisterHook(
    eventType events.WindowEventType,
    callback func(event *WindowEvent),
) func()

Example - Prevent window close:

import "github.com/wailsapp/wails/v3/pkg/events"

window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    confirm := app.Dialog.Question().
        SetTitle("Confirm Close").
        SetMessage("Are you sure you want to close this window?")

    yes := confirm.AddButton("Yes")
    no := confirm.AddButton("No")
    confirm.SetDefaultButton(yes)
    confirm.SetCancelButton(no)

    no.OnClick(func() {
        e.Cancel() // Prevent window from closing
    })

    confirm.Show()
})

Example - Save before closing:

window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    if !hasUnsavedChanges {
        return
    }

    dlg := app.Dialog.Question().
        SetTitle("Unsaved Changes").
        SetMessage("Save changes before closing?")

    save := dlg.AddButton("Save")
    discard := dlg.AddButton("Don't Save")
    cancel := dlg.AddButton("Cancel")
    dlg.SetDefaultButton(save)
    dlg.SetCancelButton(cancel)

    save.OnClick(func() { saveData() })
    cancel.OnClick(func() { e.Cancel() })
    _ = discard // allow close

    dlg.Show()
})

EmitEvent()

Emits a custom event to the window’s frontend. Returns true if the emit was cancelled by a hook.

func (w *WebviewWindow) EmitEvent(name string, data ...any) bool

Parameters:

name - Event name
data - Optional data to send with the event

Example:

// Send data to specific window
window.EmitEvent("data-updated", map[string]any{
    "count":  42,
    "status": "success",
})

Frontend (JavaScript):

import { Events } from '@wailsio/runtime'

Events.On('data-updated', (data) => {
    console.log('Count:', data.count)
    console.log('Status:', data.status)
})

Other Methods

SetEnabled()

Enables or disables user interaction with the window.

func (w *WebviewWindow) SetEnabled(enabled bool)

Example:

// Disable window during long operation
window.SetEnabled(false)

// Perform operation
performLongOperation()

// Re-enable window
window.SetEnabled(true)

SetBackgroundColour()

Sets the window background colour (shown before content loads). Returns the receiver for chaining.

func (w *WebviewWindow) SetBackgroundColour(colour RGBA) Window

RGBA is application.RGBA{Red, Green, Blue, Alpha uint8}. Use the helpers application.NewRGB(r, g, b) (alpha 255) or application.NewRGBA(r, g, b, a).

Example:

// White background
window.SetBackgroundColour(application.NewRGB(255, 255, 255))

// Dark background with full alpha
window.SetBackgroundColour(application.NewRGBA(30, 30, 30, 255))

SetResizable()

Controls whether the window can be resized by the user. Returns the receiver for chaining.

func (w *WebviewWindow) SetResizable(resizable bool) Window

Example:

// Make window fixed size
window.SetResizable(false)

SetAlwaysOnTop()

Sets whether the window stays above other windows. Returns the receiver for chaining.

func (w *WebviewWindow) SetAlwaysOnTop(alwaysOnTop bool) Window

Example:

// Keep window on top
window.SetAlwaysOnTop(true)

Print()

Opens the native print dialog for the window content.

func (w *WebviewWindow) Print() error

Returns: Error if printing fails.

Example:

if err := window.Print(); err != nil {
    log.Println("Print failed:", err)
}

AttachModal()

Attaches a second window as a sheet modal.

func (w *WebviewWindow) AttachModal(modalWindow Window)

Parameters:

modalWindow - The window to attach as a modal

Platform support:

macOS: Full support (presents as a sheet)
Windows: No support
Linux: No support

Example:

modalWindow := app.Window.New()
window.AttachModal(modalWindow)

Platform-Specific Options

Linux

Linux windows support the following platform-specific options via LinuxWindow:

MenuStyle

Controls how the application menu is displayed. This option is available on the default GTK4 build and is ignored on legacy -tags gtk3 builds.

Value	Description
`LinuxMenuStyleMenuBar`	Traditional menu bar below the title bar (default)
`LinuxMenuStylePrimaryMenu`	Primary menu button in the header bar (GNOME style)

Example:

window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title: "My Application",
    Linux: application.LinuxWindow{
        MenuStyle: application.LinuxMenuStylePrimaryMenu,
    },
})
window.SetMenu(menu)

Note: The primary menu style displays a hamburger button (☰) in the header bar, following GNOME Human Interface Guidelines. This is the recommended style for modern GNOME applications.

Complete Example

package main

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

func main() {
    app := application.New(application.Options{
        Name: "Window API Demo",
    })

    // Create window with options
    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title:            "My Application",
        Width:            1024,
        Height:           768,
        MinWidth:         800,
        MinHeight:        600,
        BackgroundColour: application.NewRGB(255, 255, 255),
        URL:              "http://wails.localhost/",
    })

    // Configure window behaviour
    window.SetResizable(true)
    window.SetMinSize(800, 600)
    window.SetMaxSize(1920, 1080)

    // Confirm-before-close hook
    window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
        dlg := app.Dialog.Question().
            SetTitle("Confirm Close").
            SetMessage("Are you sure you want to close this window?")

        yes := dlg.AddButton("Yes")
        no := dlg.AddButton("No")
        dlg.SetDefaultButton(yes)
        dlg.SetCancelButton(no)
        no.OnClick(func() { e.Cancel() })

        dlg.Show()
    })

    // Listen for window events
    window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
        window.SetTitle("My Application (Active)")
        app.Logger.Info("Window gained focus")
    })

    window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
        window.SetTitle("My Application")
        app.Logger.Info("Window lost focus")
    })

    // Position and show window
    window.Center()
    window.Show()

    app.Run()
}