Window Options

Window Configuration Options

Wails provides comprehensive window configuration with dozens of options for size, position, appearance, and behaviour. This reference covers all available options across Windows, macOS, and Linux as the complete reference for WebviewWindowOptions. Every option, every platform, with examples and constraints.

WebviewWindowOptions Structure

type WebviewWindowOptions struct {
    // Identity
    Name  string
    Title string

    // Size and Position
    Width     int
    Height    int
    X         int
    Y         int
    MinWidth  int
    MinHeight int
    MaxWidth  int
    MaxHeight int

    // Initial State
    Hidden          bool
    Frameless       bool
    Resizable       bool
    AlwaysOnTop     bool
    Fullscreen      bool
    Minimised       bool
    Maximised       bool
    WindowState     WindowState

    // Appearance
    BackgroundColour RGBA
    BackgroundType   BackgroundType

    // Content
    URL  string
    HTML string

    // Assets
    Assets application.AssetOptions

    // Security
    ContentProtectionEnabled bool

    // Menu
    UseApplicationMenu bool

    // Lifecycle
    OnClose   func() bool
    OnDestroy func()

    // Platform-Specific
    Mac     MacOptions
    Windows WindowsOptions
    Linux   LinuxOptions
}

Core Options

Name

Type: string
Default: Auto-generated UUID
Platform: All

Name: "main-window"

Purpose: Unique identifier for finding windows later.

Best practices:

• Use descriptive names: "main", "settings", "about"
• Use kebab-case: "file-browser", "color-picker"
• Keep it short and memorable

Example:

window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Name: "settings-window",
})

// Later...
settings := app.GetWindowByName("settings-window")

Title

Type: string
Default: Application name
Platform: All

Title: "My Application"

Purpose: Text shown in title bar and taskbar.

Dynamic updates:

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

Width / Height

Type: int (pixels)
Default: 800 x 600
Platform: All
Constraints: Must be positive

Width:  1200,
Height: 800,

Purpose: Initial window size in logical pixels.

Notes:

• Wails handles DPI scaling automatically
• Use logical pixels, not physical pixels
• Consider minimum screen resolution (1024x768)

Example sizes:

Use Case	Width	Height
Small utility	400	300
Standard app	1024	768
Large app	1440	900
Full HD	1920	1080

X / Y

Type: int (pixels)
Default: Centred on screen
Platform: All

X: 100,  // 100px from left edge
Y: 100,  // 100px from top edge

Purpose: Initial window position.

Coordinate system:

• (0, 0) is top-left of primary screen
• Positive X goes right
• Positive Y goes down

Example:

settings := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Name: "coordinate-window",
    InitialPosition: application.WindowXY, // use coordinate system
    X:    100,
    Y:    100,
})

**Best practice:** Use `Center()` to center the window:

```go
window := app.Window.New()
window.Center()

MinWidth / MinHeight

Type: int (pixels)
Default: 0 (no minimum)
Platform: All

MinWidth:  400,
MinHeight: 300,

Purpose: Prevent window from being too small.

Use cases:

• Prevent broken layouts
• Ensure usability
• Maintain aspect ratio

Example:

// Prevent window smaller than 400x300
MinWidth:  400,
MinHeight: 300,

MaxWidth / MaxHeight

Type: int (pixels)
Default: 0 (no maximum)
Platform: All

MaxWidth:  1920,
MaxHeight: 1080,

Purpose: Prevent window from being too large.

Use cases:

• Fixed-size applications
• Prevent excessive resource usage
• Maintain design constraints

State Options

Hidden

Type: bool Default: false Platform: All

Hidden: true,

Purpose: Create window without showing it.

Use cases:

• Background windows
• Windows shown on demand
• Splash screens (create, load, then show)
• Prevent white flash while loading content

Platform improvements:

• Windows: Fixed white window flash - window stays invisible until Show() is called
• macOS: Full support
• Linux: Full support

Recommended pattern for smooth loading:

// Create hidden window
window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Name:   "main-window",
    Hidden: true,
    BackgroundColour: application.RGBA{R: 30, G: 30, B: 30, A: 255}, // Match your theme
})

// Load content while hidden
// ... content loads ...

// Show when ready (no flash!)
window.Show()

Example:

settings := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Name:   "settings",
    Hidden: true,
})

// Show when needed
settings.Show()

Frameless

Type: bool
Default: false
Platform: All

Frameless: true,

Purpose: Remove title bar and window borders.

Use cases:

• Custom window chrome
• Splash screens
• Kiosk applications
• Custom-designed windows

Important: You’ll need to implement:

• Window dragging
• Close/minimise/maximise buttons
• Resize handles (if resizable)

See Frameless Windows for details.

Resizable

Type: bool
Default: true
Platform: All

Resizable: false,

Purpose: Allow/prevent window resizing.

Use cases:

• Fixed-size applications
• Splash screens
• dialogs

Note: Users can still maximise/fullscreen unless you prevent those too.

AlwaysOnTop

Type: bool
Default: false
Platform: All

AlwaysOnTop: true,

Purpose: Keep window above all other windows.

Use cases:

• Floating toolbars
• Notifications
• Picture-in-picture
• Timers

Platform notes:

• macOS: Full support
• Windows: Full support
• Linux: Depends on window manager

Fullscreen

Type: bool
Default: false
Platform: All

Fullscreen: true,

Purpose: Start in fullscreen mode.

Platform behaviour:

• macOS: Creates new Space (virtual desktop)
• Windows: Covers taskbar
• Linux: Varies by desktop environment

Toggle at runtime:

window.Fullscreen()
window.UnFullscreen()

Minimised / Maximised

Type: bool
Default: false
Platform: All

Minimised: true,  // Start minimised
Maximised: true,  // Start maximised

Purpose: Set initial window state.

Note: Don’t set both to true - behaviour is undefined.

WindowState

Type: WindowState enum
Default: WindowStateNormal
Platform: All

WindowState: application.WindowStateMaximised,

Values:

• WindowStateNormal - Normal window
• WindowStateMinimised - Minimised
• WindowStateMaximised - Maximised
• WindowStateFullscreen - Fullscreen
• WindowStateHidden - Hidden

Preferred over individual flags:

// ✅ Preferred
WindowState: application.WindowStateMaximised,

// ❌ Avoid
Maximised: true,

Appearance Options

BackgroundColour

Type: RGBA struct
Default: White (255, 255, 255, 255)
Platform: All

BackgroundColour: application.RGBA{R: 0, G: 0, H: 0, A: 255},

Purpose: Window background colour before content loads.

Use cases:

• Match your app’s theme
• Prevent white flash on dark themes
• Smooth loading experience

Example:

// Dark theme
BackgroundColour: application.RGBA{R: 30, G: 30, B: 30, A: 255},

// Light theme
BackgroundColour: application.RGBA{R: 255, G: 255, B: 255, A: 255},

Helper method:

window.SetBackgroundColour(30, 30, 30, 255)

BackgroundType

Type: BackgroundType enum
Default: BackgroundTypeSolid
Platform: macOS, Windows (partial)

BackgroundType: application.BackgroundTypeTranslucent,

Values:

• BackgroundTypeSolid - Solid colour
• BackgroundTypeTransparent - Fully transparent
• BackgroundTypeTranslucent - Semi-transparent blur

Platform support:

• macOS: All types supported
• Windows: Transparent and Translucent (Windows 11+)
• Linux: Solid only

Example (macOS):

BackgroundType: application.BackgroundTypeTranslucent,
Mac: application.MacOptions{
    Backdrop: application.MacBackdropTranslucent,
},

Content Options

URL

Type: string
Default: Empty (loads from Assets)
Platform: All

URL: "https://example.com",

Purpose: Load external URL instead of embedded assets.

Use cases:

• Development (load from dev server)
• Web-based applications
• Hybrid applications

Example:

// Development
URL: "http://localhost:5173",

// Production
Assets: application.AssetOptions{
    Handler: application.AssetFileServerFS(assets),
},

HTML

Type: string
Default: Empty
Platform: All

HTML: "<h1>Hello World</h1>",

Purpose: Load HTML string directly.

Use cases:

• Simple windows
• Generated content
• Testing

Example:

HTML: `
<!DOCTYPE html>
<html>
<head><title>Simple Window</title></head>
<body><h1>Hello from Wails!</h1></body>
</html>
`,

Assets

Type: AssetOptions
Default: Inherited from application
Platform: All

Assets: application.AssetOptions{
    Handler: application.AssetFileServerFS(assets),
},

Purpose: Serve embedded frontend assets.

See Build System for details.

UseApplicationMenu

Type: bool Default: false Platform: Windows, Linux (no effect on macOS)

UseApplicationMenu: true,

Purpose: Use the application menu (set via app.Menu.Set()) for this window.

On macOS, this option has no effect because macOS always uses a global application menu at the top of the screen.

On Windows and Linux, windows don’t display a menu by default. Setting UseApplicationMenu: true tells the window to use the application-level menu, providing a simple cross-platform solution.

Example:

// Set the application menu once
menu := app.NewMenu()
menu.AddRole(application.FileMenu)
menu.AddRole(application.EditMenu)
app.Menu.Set(menu)

// All windows with UseApplicationMenu will display this menu
app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:              "Main Window",
    UseApplicationMenu: true,
})

app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:              "Second Window",
    UseApplicationMenu: true,  // Also gets the app menu
})

Notes:

• If both UseApplicationMenu and a window-specific menu are set, the window-specific menu takes priority
• This simplifies cross-platform code by eliminating the need for runtime OS checks
• See Application Menus for complete menu documentation

Input Options

EnableFileDrop

Type: bool
Default: false
Platform: All

EnableFileDrop: true,

Purpose: Enable drag-and-drop of files from the operating system into the window.

When enabled:

• Files dragged from file managers can be dropped into your application
• The WindowFilesDropped event fires with the dropped file paths
• Elements with data-file-drop-target attribute provide detailed drop information

Use cases:

• File upload interfaces
• Document editors
• Media importers
• Any app that accepts files

Example:

window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:          "File Uploader",
    EnableFileDrop: true,
})

// Handle dropped files
window.OnWindowEvent(events.Common.WindowFilesDropped, func(event *application.WindowEvent) {
    files := event.Context().DroppedFiles()
    details := event.Context().DropTargetDetails()

    for _, file := range files {
        fmt.Println("Dropped:", file)
    }
})

HTML drop zones:

<!-- Mark elements as drop targets -->
<div id="upload" data-file-drop-target>
    Drop files here
</div>

See File Drop for complete documentation.

Security Options

ContentProtectionEnabled

Type: bool
Default: false
Platform: Windows (10+), macOS

ContentProtectionEnabled: true,

Purpose: Prevent screen capture of window contents.

Platform support:

• Windows: Windows 10 build 19041+ (full), older versions (partial)
• macOS: Full support
• Linux: Not supported

Use cases:

• Banking applications
• Password managers
• Medical records
• Confidential documents

Important notes:

1. Doesn’t prevent physical photography
2. Some tools may bypass protection
3. Part of comprehensive security, not sole protection
4. DevTools windows not protected automatically

Example:

window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title: "Secure Window",
    ContentProtectionEnabled: true,
})

// Toggle at runtime
window.SetContentProtection(true)

Lifecycle Options

OnClose

Type: func() bool
Default: nil (always allow close)
Platform: All

OnClose: func() bool {
    // Return false to cancel close
    // Return true to allow close
    return true
},

Purpose: Handle window close events, optionally prevent closing.

Use cases:

• Confirm before closing with unsaved changes
• Save state before closing
• Prevent accidental closure

Example:

OnClose: func() bool {
    if hasUnsavedChanges() {
        result := showConfirmdialog("Unsaved changes. Close anyway?")
        return result == "yes"
    }
    return true
},

Important: Only triggered by user actions (clicking X), not window.Destroy().

OnDestroy

Type: func()
Default: nil
Platform: All

OnDestroy: func() {
    // Cleanup code
    fmt.Println("Window destroyed")
},

Purpose: Cleanup when window is destroyed.

Use cases:

• Release resources
• Close connections
• Update application state

Example:

OnDestroy: func() {
    // Close database connection
    if db != nil {
        db.Close()
    }

    // Remove from window list
    removeWindow(window.ID())
},

Platform-Specific Options

Mac Options

Mac: application.MacWindow{
    TitleBar: application.MacTitleBar{
        AppearsTransparent: true,
        Hide:               false,
        HideTitle:          true,
        FullSizeContent:    true,
    },
    Backdrop:                application.MacBackdropTranslucent,
    InvisibleTitleBarHeight: 50,
    WindowLevel:             application.MacWindowLevelNormal,
    CollectionBehavior:      application.MacWindowCollectionBehaviorDefault,
},

TitleBar (MacTitleBar)

• AppearsTransparent - Makes title bar transparent, content extends into title bar area
• Hide - Hides the title bar completely
• HideTitle - Hides only the title text
• FullSizeContent - Extends content to full window size

Backdrop (MacBackdrop)

• MacBackdropNormal - Standard opaque background
• MacBackdropTranslucent - Blurred translucent background
• MacBackdropTransparent - Fully transparent background

InvisibleTitleBarHeight (int)

• Height of invisible title bar area (for dragging)
• Only takes effect when the native title bar drag area is hidden — i.e. when the window is frameless (Frameless: true) or uses a transparent title bar (AppearsTransparent: true)
• Has no effect on standard windows with a visible title bar

WindowLevel (MacWindowLevel)

• MacWindowLevelNormal - Standard window level (default)
• MacWindowLevelFloating - Floats above normal windows
• MacWindowLevelTornOffMenu - Torn-off menu level
• MacWindowLevelModalPanel - Modal panel level
• MacWindowLevelMainMenu - Main menu level
• MacWindowLevelStatus - Status window level
• MacWindowLevelPopUpMenu - Pop-up menu level
• MacWindowLevelScreenSaver - Screen saver level

CollectionBehavior (MacWindowCollectionBehavior)

Controls how the window behaves across macOS Spaces and fullscreen. These are bitmask values that can be combined using bitwise OR (|).

Space behavior:

• MacWindowCollectionBehaviorDefault - Uses FullScreenPrimary (default, backwards compatible)
• MacWindowCollectionBehaviorCanJoinAllSpaces - Window appears on all Spaces
• MacWindowCollectionBehaviorMoveToActiveSpace - Moves to active Space when shown
• MacWindowCollectionBehaviorManaged - Default managed window behavior
• MacWindowCollectionBehaviorTransient - Temporary/transient window
• MacWindowCollectionBehaviorStationary - Stays stationary during Space switches

Window cycling:

• MacWindowCollectionBehaviorParticipatesInCycle - Included in Cmd+` cycling
• MacWindowCollectionBehaviorIgnoresCycle - Excluded from Cmd+` cycling

Fullscreen behavior:

• MacWindowCollectionBehaviorFullScreenPrimary - Can enter fullscreen mode
• MacWindowCollectionBehaviorFullScreenAuxiliary - Can overlay fullscreen apps
• MacWindowCollectionBehaviorFullScreenNone - Disables fullscreen capability
• MacWindowCollectionBehaviorFullScreenAllowsTiling - Allows side-by-side tiling (macOS 10.11+)
• MacWindowCollectionBehaviorFullScreenDisallowsTiling - Prevents tiling (macOS 10.11+)

Example - Spotlight-like window:

// Window that appears on all Spaces AND can overlay fullscreen apps
Mac: application.MacWindow{
    CollectionBehavior: application.MacWindowCollectionBehaviorCanJoinAllSpaces |
                        application.MacWindowCollectionBehaviorFullScreenAuxiliary,
    WindowLevel:        application.MacWindowLevelFloating,
},

Example - Single behavior:

// Window that can appear over fullscreen applications
Mac: application.MacWindow{
    CollectionBehavior: application.MacWindowCollectionBehaviorFullScreenAuxiliary,
},

Windows Options

Windows: application.WindowsOptions{
    DisableWindowIcon:      false,
    WindowBackdropType:     application.WindowsBackdropTypeAuto,
    CustomTheme:            nil,
    DisableFramelessWindowDecorations: false,
},

DisableWindowIcon (bool)

• Remove icon from title bar
• Cleaner appearance

WindowBackdropType (WindowsBackdropType)

• WindowsBackdropTypeAuto - System default
• WindowsBackdropTypeNone - No backdrop
• WindowsBackdropTypeMica - Mica material (Windows 11)
• WindowsBackdropTypeAcrylic - Acrylic material (Windows 11)
• WindowsBackdropTypeTabbed - Tabbed material (Windows 11)

CustomTheme (*WindowsTheme)

• Custom colour theme
• Override system colours

DisableFramelessWindowDecorations (bool)

• Disable default frameless decorations
• For custom window chrome

Example:

Windows: application.WindowsOptions{
    WindowBackdropType: application.WindowsBackdropTypeMica,
    DisableWindowIcon:  true,
},

Linux Options

Linux: application.LinuxOptions{
    Icon:                []byte{/* PNG data */},
    WindowIsTranslucent: false,
},

Icon ([]byte)

• Window icon (PNG format)
• Shown in title bar and taskbar

WindowIsTranslucent (bool)

• Enable window translucency
• Requires compositor support

Example:

//go:embed icon.png
var icon []byte

Linux: application.LinuxOptions{
    Icon: icon,
},

Application-Level Windows Options

Some Windows-specific options must be configured at the application level rather than per-window. This is because WebView2 shares a single browser environment per user data path.

Browser Flags

WebView2 browser flags control experimental features and behavior across all windows in your application. These must be set in application.Options.Windows:

app := application.New(application.Options{
    Name: "My App",
    Windows: application.WindowsOptions{
        // Enable experimental WebView2 features
        EnabledFeatures: []string{
            "msWebView2EnableDraggableRegions",
        },

        // Disable specific features
        DisabledFeatures: []string{
            "msSmartScreenProtection",  // Always disabled by Wails
        },

        // Additional Chromium command-line arguments
        AdditionalBrowserArgs: []string{
            "--disable-gpu",
            "--remote-debugging-port=9222",
        },
    },
})

EnabledFeatures ([]string)

• List of WebView2 feature flags to enable
• See WebView2 browser flags for available flags
• Example: "msWebView2EnableDraggableRegions"

DisabledFeatures ([]string)

• List of WebView2 feature flags to disable
• Wails automatically disables msSmartScreenProtection
• Example: "msExperimentalFeature"

AdditionalBrowserArgs ([]string)

• Chromium command-line arguments passed to the browser process
• Must include the -- prefix (e.g., "--remote-debugging-port=9222")
• See Chromium command line switches for available arguments

Important

These flags apply globally to ALL windows because WebView2 shares a single browser environment per user data path. You cannot have different browser flags for different windows.

Complete Example:

package main

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

func main() {
    app := application.New(application.Options{
        Name: "My App",
        Windows: application.WindowsOptions{
            // Enable draggable regions feature
            EnabledFeatures: []string{
                "msWebView2EnableDraggableRegions",
            },
            // Enable remote debugging
            AdditionalBrowserArgs: []string{
                "--remote-debugging-port=9222",
            },
        },
    })

    // All windows will use the browser flags configured above
    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title:  "Main Window",
        Width:  1024,
        Height: 768,
    })

    window.Show()
    app.Run()
}

Complete Example

Here’s a production-ready window configuration:

package main

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

//go:embed frontend/dist
var assets embed.FS

//go:embed icon.png
var icon []byte

func main() {
    app := application.New(application.Options{
        Name: "My Application",
    })

    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        // Identity
        Name:  "main-window",
        Title: "My Application",

        // Size and Position
        Width:     1200,
        Height:    800,
        MinWidth:  800,
        MinHeight: 600,

        // Initial State
        WindowState: application.WindowStateNormal,
        Resizable:   true,

        // Appearance
        BackgroundColour: application.RGBA{R: 255, G: 255, B: 255, A: 255},

        // Content
        Assets: application.AssetOptions{
            Handler: application.AssetFileServerFS(assets),
        },

        // Lifecycle
        OnClose: func() bool {
            if hasUnsavedChanges() {
                result := showConfirmdialog("Unsaved changes. Close anyway?")
                return result == "yes"
            }
            return true
        },

        OnDestroy: func() {
            cleanup()
        },

        // Platform-Specific
        Mac: application.MacOptions{
            TitleBarAppearsTransparent: true,
            Backdrop:                   application.MacBackdropTranslucent,
        },

        Windows: application.WindowsOptions{
            WindowBackdropType: application.WindowsBackdropTypeMica,
            DisableWindowIcon:  false,
        },

        Linux: application.LinuxOptions{
            Icon: icon,
        },
    })

    window.Center()
    window.Show()

    app.Run()
}

Next Steps

• Window Basics - Creating and controlling windows
• Multiple Windows - Multi-window patterns
• Frameless Windows - Custom window chrome
• Window Events - Lifecycle events

---

Questions? Ask in Discord or check the examples.