Customising Windows in Wails

Relevant Platforms: Windows macOS

Wails provides an API to control the appearance and functionality of the controls of a window. This functionality is available on Windows and macOS, but not on Linux.

Setting the Window Button States

The button states are defined by the ButtonState enum:

type ButtonState int

const (
    ButtonEnabled   ButtonState = 0
    ButtonDisabled  ButtonState = 1
    ButtonHidden    ButtonState = 2
)

• ButtonEnabled: The button is enabled and visible.
• ButtonDisabled: The button is visible but disabled (grayed out).
• ButtonHidden: The button is hidden from the titlebar.

The button states can be set during window creation or at runtime.

Setting Button States During Window Creation

When creating a new window, you can set the initial state of the buttons using the WebviewWindowOptions struct:

main.go

package main

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

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

    app.Window.NewWithOptions(application.WebviewWindowOptions{
        MinimiseButtonState:   application.ButtonHidden,
        MaximiseButtonState:   application.ButtonDisabled,
        CloseButtonState:      application.ButtonEnabled,
        FullscreenButtonState: application.ButtonEnabled,
    })

    app.Run()
}

In the example above, the minimise button is hidden, the maximise button is inactive (grayed out), and the close button is active.

Setting Button States at Runtime

You can also change the button states at runtime using the following methods on the Window interface:

window.SetMinimiseButtonState(wails.ButtonHidden)
window.SetMaximiseButtonState(wails.ButtonEnabled)
window.SetCloseButtonState(wails.ButtonDisabled)
window.SetFullscreenButtonState(wails.ButtonEnabled)

macOS: MaximiseButtonState and FullscreenButtonState share a button

On macOS the green traffic-light button (NSWindowZoomButton) is the same physical control for both maximise and fullscreen. Setting MaximiseButtonState and FullscreenButtonState to different values during window creation would otherwise produce a silent last-writer-wins override.

To avoid this, Wails applies the more restrictive of the two states at initialisation, in the order ButtonEnabled < ButtonDisabled < ButtonHidden.

MaximiseButtonState	FullscreenButtonState	Effective state on macOS
ButtonEnabled	ButtonEnabled	ButtonEnabled
ButtonDisabled	ButtonEnabled	ButtonDisabled
ButtonEnabled	ButtonHidden	ButtonHidden
ButtonDisabled	ButtonHidden	ButtonHidden

At runtime, SetMaximiseButtonState and SetFullscreenButtonState both target NSWindowZoomButton on macOS, so the last call wins.

Platform Differences

The button state functionality behaves slightly differently on Windows and macOS:

	Windows	Mac
Disable Min/Max/Close	Disables Min/Max/Close	Disables Min/Max/Close
Hide Min	Disables Min	Hides Min button
Hide Max	Disables Max	Hides Max button
Hide Close	Hides all controls	Hides Close
FullscreenButtonState	No-op	Targets the zoom (green) button

Note: On Windows, it is not possible to hide the Min/Max buttons individually. However, disabling both will hide both of the controls and only show the close button. Windows has no dedicated fullscreen button in the standard title bar, so FullscreenButtonState is a no-op there.

Controlling Window Style (Windows)

To control the style of the titlebar on Windows, you can use the ExStyle field in the WebviewWindowOptions struct:

Example:

main.go

package main

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

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

    app.Window.NewWithOptions(application.WebviewWindowOptions{
        Windows: application.WindowsWindow{
            ExStyle: w32.WS_EX_TOOLWINDOW | w32.WS_EX_NOREDIRECTIONBITMAP | w32.WS_EX_TOPMOST,
        },
    })

    app.Run()
}

Other options that affect the Extended Style of a window will be overridden by this setting:

• HiddenOnTaskbar
• AlwaysOnTop
• IgnoreMouseEvents
• BackgroundType