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()
}