Pular para o conteúdo principal
Versão: v2.8.0

Options

Application Options​

The Options.App struct contains the application configuration. It is passed to the wails.Run() method:

Example
import (
    "github.com/wailsapp/wails/v2/pkg/options"
    "github.com/wailsapp/wails/v2/pkg/options/assetserver"
    "github.com/wailsapp/wails/v2/pkg/options/linux"
    "github.com/wailsapp/wails/v2/pkg/options/mac"
    "github.com/wailsapp/wails/v2/pkg/options/windows"
)

func main() {

    err := wails.Run(&options.App{
        Title:              "Menus Demo",
        Width:              800,
        Height:             600,
        DisableResize:      false,
        Fullscreen:         false,
        WindowStartState:   options.Maximised,
        Frameless:          true,
        MinWidth:           400,
        MinHeight:          400,
        MaxWidth:           1280,
        MaxHeight:          1024,
        StartHidden:        false,
        HideWindowOnClose:  false,
        BackgroundColour:   &options.RGBA{R: 0, G: 0, B: 0, A: 255},
        AlwaysOnTop:        false,
        AssetServer: &assetserver.Options{
            Assets:     assets,
            Handler:    assetsHandler,
            Middleware: assetsMidldeware,
        },
        Menu:               app.applicationMenu(),
        Logger:             nil,
        LogLevel:           logger.DEBUG,
        LogLevelProduction: logger.ERROR,
        OnStartup:          app.startup,
        OnDomReady:         app.domready,
        OnShutdown:         app.shutdown,
        OnBeforeClose:      app.beforeClose,
        CSSDragProperty:   "--wails-draggable",
        CSSDragValue:      "drag",
        EnableDefaultContextMenu: false,
        EnableFraudulentWebsiteDetection: false,
        ZoomFactor:           1.0,
        IsZoomControlEnabled: false,
        Bind: []interface{}{
            app,
        },
        ErrorFormatter: func(err error) any { return err.Error() },
        Windows: &windows.Options{
            WebviewIsTransparent:              false,
            WindowIsTranslucent:               false,
            BackdropType:                      windows.Mica,
            DisableWindowIcon:                 false,
            DisableFramelessWindowDecorations: false,
            WebviewUserDataPath:               "",
            WebviewBrowserPath:                "",
            Theme:                             windows.SystemDefault,
            CustomTheme: &windows.ThemeSettings{
                DarkModeTitleBar:   windows.RGB(20, 20, 20),
                DarkModeTitleText:  windows.RGB(200, 200, 200),
                DarkModeBorder:     windows.RGB(20, 0, 20),
                LightModeTitleBar:  windows.RGB(200, 200, 200),
                LightModeTitleText: windows.RGB(20, 20, 20),
                LightModeBorder:    windows.RGB(200, 200, 200),
            },
            // User messages that can be customised
            Messages *windows.Messages
            // OnSuspend is called when Windows enters low power mode
            OnSuspend func()
            // OnResume is called when Windows resumes from low power mode
            OnResume func(),
            WebviewGpuDisabled: false,
        },
        Mac: &mac.Options{
            TitleBar: &mac.TitleBar{
                TitlebarAppearsTransparent: true,
                HideTitle:                  false,
                HideTitleBar:               false,
                FullSizeContent:            false,
                UseToolbar:                 false,
                HideToolbarSeparator:       true,
            },
            Appearance:           mac.NSAppearanceNameDarkAqua,
            WebviewIsTransparent: true,
            WindowIsTranslucent:  false,
            About: &mac.AboutInfo{
                Title:   "My Application",
                Message: "© 2021 Me",
                Icon:    icon,
            },
        },
        Linux: &linux.Options{
            Icon: icon,
            WindowIsTranslucent: false,
            WebviewGpuPolicy: linux.WebviewGpuPolicyAlways,
            ProgramName: "wails"
        },
        Debug: options.Debug{
            OpenInspectorOnStartup: false,
        },
    })

    if err != nil {
        log.Fatal(err)
    }
}

Title​

The text shown in the window's title bar.

Name: Title
Type: string

Width​

The initial width of the window.

Name: Width
Type: int
Default: 1024.

Height​

The initial height of the window.

Name: Height
Type: int
Default: 768

DisableResize​

By default, the main window is resizable. Setting this to true will keep it a fixed size.

Name: DisableResize
Type: bool

Fullscreen​

Deprecated: Please use WindowStartState.

WindowStartState​

Defines how the window should present itself at startup.

ValueWinMacLin
Fullscreen✅✅✅
Maximised✅✅✅
Minimised✅❌✅

Name: WindowStartState
Type: options.WindowStartState

Frameless​

When set to true, the window will have no borders or title bar. Also see Frameless Windows.

Name: Frameless
Type: bool

MinWidth​

This sets the minimum width for the window. If the value given in Width is less than this value, the window will be set to MinWidth by default.

Name: MinWidth
Type: int

MinHeight​

This sets the minimum height for the window. If the value given in Height is less than this value, the window will be set to MinHeight by default.

Name: MinHeight
Type: int

MaxWidth​

This sets the maximum width for the window. If the value given in Width is more than this value, the window will be set to MaxWidth by default.

Name: MaxWidth
Type: int

MaxHeight​

This sets the maximum height for the window. If the value given in Height is more than this value, the window will be set to MaxHeight by default.

Name: MaxHeight
Type: int

StartHidden​

When set to true, the application will be hidden until WindowShow is called.

Name: StartHidden
Type: bool

HideWindowOnClose​

By default, closing the window will close the application. Setting this to true means closing the window will

hide the window instead.

Name: HideWindowOnClose
Type: bool

BackgroundColour​

This value is the default background colour of the window. Example: options.NewRGBA(255,0,0,128) - Red at 50% transparency

Name: BackgroundColour
Type: *options.RGBA
Default: white

AlwaysOnTop​

Indicates that the window should stay above other windows when losing focus.

Name: AlwaysOnTop
Type: bool

Assets​

Deprecated: Please use Assets on AssetServer specific options.

AssetsHandler​

Deprecated: Please use AssetsHandler on AssetServer specific options.

AssetServer​

This defines AssetServer specific options. It allows to customize the AssetServer with static assets, serving assets dynamically with an http.Handler or hook into the request chain with an assetserver.Middleware.

Not all features of an http.Request are currently supported, please see the following feature matrix:

FeatureWinMacLin
GET✅✅✅
POST✅✅✅ 1
PUT✅✅✅ 1
PATCH✅✅✅ 1
DELETE✅✅✅ 1
Request Headers✅✅✅ 1
Request Body✅✅✅ 2
Request Body Streaming✅✅✅ 2
Response StatusCodes✅✅✅ 1
Response Headers✅✅✅ 1
Response Body✅✅✅
Response Body Streaming❌✅✅
WebSockets❌❌❌
HTTP Redirects 30x✅❌❌

Name: AssetServer
Type: *assetserver.Options

Assets​

The static frontend assets to be used by the application.

A GET request is first tried to be served from this fs.FS. If the fs.FS returns os.ErrNotExist for that file, the request handling will fallback to the Handler and tries to serve the GET request from it.

If set to nil, all GET requests will be forwarded to Handler.

Name: Assets
Type: fs.FS

Handler​

The assets handler is a generic http.Handler for fallback handling of assets that can't be found.

The handler will be called for every GET request that can't be served from Assets, due to os.ErrNotExist. Furthermore all non GET requests will always be served from this Handler. If not defined, the result is the following in cases where the Handler would have been called:

  • GET request: http.StatusNotFound
  • Other request: http.StatusMethodNotAllowed

NOTE: When used in combination with a Frontend DevServer there might be limitations, eg. Vite serves the index.html on every path, that does not contain a file extension.

Name: AssetsHandler
Type: http.Handler

Middleware​

Middleware is a HTTP Middleware which allows to hook into the AssetServer request chain. It allows to skip the default request handler dynamically, e.g. implement specialized Routing etc. The Middleware is called to build a new http.Handler used by the AssetSever and it also receives the default handler used by the AssetServer as an argument.

If not defined, the default AssetServer request chain is executed.

Name: Middleware
Type: assetserver.Middleware

The menu to be used by the application. More details about Menus in the Menu Reference.

note

On Mac, if no menu is specified, a default menu will be created.

Name: Menu
Type: *menu.Menu

Logger​

The logger to be used by the application. More details about logging in the Log Reference.

Name: Logger
Type: logger.Logger
Default: Logs to Stdout

LogLevel​

The default log level. More details about logging in the Log Reference.

Name: LogLevel
Type: logger.LogLevel
Default: Info in dev mode, Error in production mode

LogLevelProduction​

The default log level for production builds. More details about logging in the Log Reference.

Name: LogLevelProduction
Type: logger.LogLevel
Default: Error

OnStartup​

This callback is called after the frontend has been created, but before index.html has been loaded. It is given the application context.

Name: OnStartup
Type: func(ctx context.Context)

OnDomReady​

This callback is called after the frontend has loaded index.html and its resources. It is given the application context.

Name: OnDomReady
Type: func(ctx context.Context)

OnShutdown​

This callback is called after the frontend has been destroyed, just before the application terminates. It is given the application context.

Name: OnShutdown
Type: func(ctx context.Context)

OnBeforeClose​

If this callback is set, it will be called when the application is about to quit, either by clicking the window close button or calling runtime.Quit. Returning true will cause the application to continue, false will continue shutdown as normal. This is good for confirming with the user that they wish to exit the program.

Example:

windowsapp.go
func (b *App) beforeClose(ctx context.Context) (prevent bool) {
    dialog, err := runtime.MessageDialog(ctx, runtime.MessageDialogOptions{
        Type:          runtime.QuestionDialog,
        Title:         "Quit?",
        Message:       "Are you sure you want to quit?",
    })

    if err != nil {
        return false
    }
    return dialog != "Yes"
}

Name: OnBeforeClose
Type: func(ctx context.Context) bool

CSSDragProperty​

Indicates the CSS property to use to identify which elements can be used to drag the window. Default: --wails-draggable.

Name: CSSDragProperty
Type: string

CSSDragValue​

Indicates what value the CSSDragProperty style should have to drag the window. Default: drag.

Name: CSSDragValue
Type: string

EnableDefaultContextMenu​

EnableDefaultContextMenu enables the browser's default context-menu in production.

By default, the browser's default context-menu is only available in development and in a -debug build along with the devtools inspector, Using this option you can enable the default context-menu in production while the devtools inspector won't be available unless the -devtools build flag is used.

When this option is enabled, by default the context-menu will only be shown for text contexts (where Cut/Copy/Paste is needed), to override this behavior, you can use the CSS property --default-contextmenu on any HTML element (including the body) with the following values :

CSS StyleBehavior
--default-contextmenu: auto;(default) will show the default context menu only if :
contentEditable is true OR text has been selected OR element is input or textarea
--default-contextmenu: show;will always show the default context menu
--default-contextmenu: hide;will always hide the default context menu

This rule is inherited like any normal CSS rule, so nesting works as expected.

note

This filtering functionality is only enabled in production, so in development and in debug build, the full context-menu is always available everywhere.

danger

This filtering functionality is NOT a security measure, the developer should expect that the full context-menu could be leaked anytime which could contain commands like (Download image, Reload, Save webpage), if this is a concern, the developer SHOULD NOT enable the default context-menu.

Name: EnableDefaultContextMenu
Type: bool

EnableFraudulentWebsiteDetection​

EnableFraudulentWebsiteDetection enables scan services for fraudulent content, such as malware or phishing attempts. These services might send information from your app like URLs navigated to and possibly other content to cloud services of Apple and Microsoft.

Name: EnableFraudulentWebsiteDetection
Type: bool

ZoomFactor​

Name: ZoomFactor
Type: float64

This defines the zoom factor for the WebView2. This is the option matching the Edge user activated zoom in or out.

IsZoomControlEnabled​

Name: IsZoomControlEnabled
Type: bool

This enables the zoom factor to be changed by the user. Please note that the zoom factor can be set in the options while disallowing the user to change it at runtime (f.e. for a kiosk application or similar).

Bind​

A slice of struct instances defining methods that need to be bound to the frontend.

Name: Bind
Type: []interface{}

ErrorFormatter​

A function that determines how errors are formatted when returned by a JS-to-Go method call. The returned value will be marshalled as JSON.

Name: ErrorFormatter
Type: func (error) any

Windows​

This defines Windows specific options.

Name: Windows
Type: *windows.Options

WebviewIsTransparent​

Setting this to true will make the webview background transparent when an alpha value of 0 is used. This means that if you use rgba(0,0,0,0) for background-color in your CSS, the host window will show through. Often combined with WindowIsTranslucent to make frosty-looking applications.

Name: WebviewIsTransparent
Type: bool

WindowIsTranslucent​

Setting this to true will make the window background translucent. Often combined with WebviewIsTransparent.

For Windows 11 versions before build 22621, this will use the BlurBehind method for translucency, which can be slow. For Windows 11 versions after build 22621, this will enable the newer translucency types that are much faster. By default, the type of translucency used will be determined by Windows. To configure this, use the BackdropType option.

Name: WindowIsTranslucent
Type: bool

BackdropType​

note

Requires Windows 11 build 22621 or later.

Sets the translucency type of the window. This is only applicable if WindowIsTranslucent is set to true.

Name: BackdropType
Type windows.BackdropType

The value can be one of the following:

ValueDescription
AutoLet Windows decide which backdrop to use
NoneDo not use translucency
AcrylicUse Acrylic effect
MicaUse Mica effect
TabbedUse Tabbed. This is a backdrop that is similar to Mica.

DisableWindowIcon​

Setting this to true will remove the icon in the top left corner of the title bar.

Name: DisableWindowIcon
Type: bool

DisableFramelessWindowDecorations​

Setting this to true will remove the window decorations in Frameless mode. This means there will be no 'Aero Shadow' and no 'Rounded Corners' shown for the window. Please note that 'Rounded Corners' are only supported on Windows 11.

Name: DisableFramelessWindowDecorations
Type: bool

WebviewUserDataPath​

This defines the path where the WebView2 stores the user data. If empty %APPDATA%\[BinaryName.exe] will be used.

Name: WebviewUserDataPath
Type: string

WebviewBrowserPath​

This defines the path to a directory with WebView2 executable files and libraries. If empty, webview2 installed in the system will be used.

Important information about distribution of fixed version runtime:

Name: WebviewBrowserPath
Type: string

Theme​

Minimum Windows Version: Windows 10 2004/20H1

This defines the theme that the application should use:

ValueDescription
SystemDefaultDefault. The theme will be based on the system default. If the user changes their theme, the application will update to use the new setting
DarkThe application will use a dark theme exclusively
LightThe application will use a light theme exclusively

Name: Theme
Type: windows.Theme

CustomTheme​

note

Minimum Windows Version: Windows 10/11 2009/21H2 Build 22000

Allows you to specify custom colours for TitleBar, TitleText and Border for both light and dark mode, as well as when the window is active or inactive.

Name: CustomTheme
Type: windows.CustomTheme

CustomTheme type​

The CustomTheme struct uses int32 to specify the colour values. These are in the standard(!) Windows format of: 0x00BBGGAA. A helper function is provided to do RGB conversions into this format: windows.RGB(r,g,b uint8).

NOTE: Any value not provided will default to black.

type ThemeSettings struct {
    DarkModeTitleBar           int32
    DarkModeTitleBarInactive   int32
    DarkModeTitleText          int32
    DarkModeTitleTextInactive  int32
    DarkModeBorder             int32
    DarkModeBorderInactive     int32
    LightModeTitleBar          int32
    LightModeTitleBarInactive  int32
    LightModeTitleText         int32
    LightModeTitleTextInactive int32
    LightModeBorder            int32
    LightModeBorderInactive    int32
}

Example:

    CustomTheme: &windows.ThemeSettings{
        // Theme to use when window is active
        DarkModeTitleBar:   windows.RGB(255, 0, 0),   // Red
        DarkModeTitleText:  windows.RGB(0, 255, 0),   // Green
        DarkModeBorder:     windows.RGB(0, 0, 255),   // Blue
        LightModeTitleBar:  windows.RGB(200, 200, 200),
        LightModeTitleText: windows.RGB(20, 20, 20),
        LightModeBorder:    windows.RGB(200, 200, 200),
        // Theme to use when window is inactive
        DarkModeTitleBarInactive:   windows.RGB(128, 0, 0),
        DarkModeTitleTextInactive:  windows.RGB(0, 128, 0),
        DarkModeBorderInactive:     windows.RGB(0, 0, 128),
        LightModeTitleBarInactive:  windows.RGB(100, 100, 100),
        LightModeTitleTextInactive: windows.RGB(10, 10, 10),
        LightModeBorderInactive:    windows.RGB(100, 100, 100),
    },

Messages​

A struct of strings used by the webview2 installer if a valid webview2 runtime is not found.

Name: Messages
Type: *windows.Messages

Customise this for any language you choose to support.

ResizeDebounceMS​

ResizeDebounceMS is the amount of time to debounce redraws of webview2 when resizing the window. The default value (0) will perform redraws as fast as it can.

Name: ResizeDebounceMS
Type: uint16

OnSuspend​

If set, this function will be called when Windows initiates a switch to low power mode (suspend/hibernate)

Name: OnSuspend
Type: func()

OnResume​

If set, this function will be called when Windows resumes from low power mode (suspend/hibernate)

Name: OnResume
Type: func()

WebviewGpuIsDisabled​

Setting this to true will disable GPU hardware acceleration for the webview.

Name: WebviewGpuIsDisabled
Type: bool

EnableSwipeGestures​

Setting this to true will enable swipe gestures for the webview.

Name: EnableSwipeGestures
Type: bool

Mac​

This defines Mac specific options.

Name: Mac
Type: *mac.Options

TitleBar​

The TitleBar struct provides the ability to configure the look and feel of the title bar.

Name: TitleBar
Type: *mac.TitleBar

Titlebar struct​

The titlebar of the application can be customised by using the TitleBar options:

type TitleBar struct {
    TitlebarAppearsTransparent bool
    HideTitle                  bool
    HideTitleBar               bool
    FullSizeContent            bool
    UseToolbar                 bool
    HideToolbarSeparator       bool
}
NameDescription
TitlebarAppearsTransparentMakes the titlebar transparent. This has the effect of hiding the titlebar and the content fill the window. Apple Docs
HideTitleHides the title of the window. Apple Docs
HideTitleBarRemoves NSWindowStyleMaskTitled from the style mask
FullSizeContentMakes the webview fill the entire window. Apple Docs
UseToolbarAdds a default toolbar to the window. Apple Docs
HideToolbarSeparatorRemoves the line beneath the toolbar. Apple Docs

Preconfigured titlebar settings are available:

SettingExample
mac.TitleBarDefault()
mac.TitleBarHidden()
mac.TitleBarHiddenInset()

Example:

Mac: &mac.Options{
    TitleBar:     mac.TitleBarHiddenInset(),
}

Click here for some inspiration on customising the titlebar.

Appearance​

Appearance is used to set the style of your app in accordance with Apple's NSAppearance names.

Name: Appearance
Type: mac.AppearanceType

Appearance type​

You can specify the application's appearance.

ValueDescription
DefaultAppearanceDefaultAppearance uses the default system value
NSAppearanceNameAquaThe standard light system appearance
NSAppearanceNameDarkAquaThe standard dark system appearance
NSAppearanceNameVibrantLightThe light vibrant appearance
NSAppearanceNameAccessibilityHighContrastAquaA high-contrast version of the standard light system appearance
NSAppearanceNameAccessibilityHighContrastDarkAquaA high-contrast version of the standard dark system appearance
NSAppearanceNameAccessibilityHighContrastVibrantLightA high-contrast version of the light vibrant appearance
NSAppearanceNameAccessibilityHighContrastVibrantDarkA high-contrast version of the dark vibrant appearance

Example:

Mac: &mac.Options{
    Appearance: mac.NSAppearanceNameDarkAqua,
}

WebviewIsTransparent​

Setting this to true will make the webview background transparent when an alpha value of 0 is used. This means that if you use rgba(0,0,0,0) for background-color in your CSS, the host window will show through. Often combined with WindowIsTranslucent to make frosty-looking applications.

Name: WebviewIsTransparent
Type: bool

WindowIsTranslucent​

Setting this to true will make the window background translucent. Often combined with WebviewIsTransparent to make frosty-looking applications.

Name: WindowIsTranslucent
Type: bool

Preferences​

The Preferences struct provides the ability to configure the Webview preferences.

Name: Preferences
Type: *mac.Preferences

Preferences struct​

You can specify the webview preferences.

type Preferences struct {
    TabFocusesLinks        u.Bool
    TextInteractionEnabled u.Bool
    FullscreenEnabled      u.Bool 
}
NameDescription
TabFocusesLinksA Boolean value that indicates whether pressing the tab key changes the focus to links and form controls. Apple Docs
TextInteractionEnabledA Boolean value that indicates whether to allow people to select or otherwise interact with text. Apple Docs
FullscreenEnabledA Boolean value that indicates whether a web view can display content full screen. Apple Docs

Example:

Mac: &mac.Options{
    Preferences: &mac.Preferences{
        TabFocusesLinks:        mac.Enabled,
        TextInteractionEnabled: mac.Disabled,
        FullscreenEnabled:      mac.Enabled,
    }
}

About​

This configuration lets you set the title, message and icon for the "About" menu item in the app menu created by the "AppMenu" role.

Name: About
Type: *mac.AboutInfo

About struct​

type AboutInfo struct {
    Title   string
    Message string
    Icon    []byte
}

If these settings are provided, an "About" menu item will appear in the app menu (when using the AppMenu role). Given this configuration:

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

func main() {
    err := wails.Run(&options.App{
        ...
        Mac: &mac.Options{
            About: &mac.AboutInfo{
                Title:   "My Application",
                Message: "© 2021 Me",
                Icon:    icon,
            },
        },
    })

The "About" menu item will appear in the app menu:


When clicked, that will open an about message box:


Linux​

This defines Linux specific options.

Name: Linux
Type: *linux.Options

Icon​

Sets up the icon representing the window. This icon is used when the window is minimized (also known as iconified).

Name: Icon
Type: []byte

Some window managers or desktop environments may also place it in the window frame, or display it in other contexts. On others, the icon is not used at all, so your mileage may vary.

NOTE: Gnome on Wayland at least does not display this icon. To have a application icon there, a .desktop file has to be used. On KDE it should work.

The icon should be provided in whatever size it was naturally drawn; that is, don’t scale the image before passing it. Scaling is postponed until the last minute, when the desired final size is known, to allow best quality.

WindowIsTranslucent​

Setting this to true will make the window background translucent. Some window managers may ignore it, or result in a black window.

Name: WindowIsTranslucent
Type: bool

WebviewGpuPolicy​

This option is used for determining the webview's hardware acceleration policy.

Name: WebviewGpuPolicy
Type: options.WebviewGpuPolicy
Default: WebviewGpuPolicyAlways

WebviewGpuPolicy type​
ValueDescription
WebviewGpuPolicyAlwaysHardware acceleration is always enabled
WebviewGpuPolicyOnDemandHardware acceleration is enabled/disabled as request by web contents
WebviewGpuPolicyNeverHardware acceleration is always disabled

ProgramName​

This option is used to set the program's name for the window manager via GTK's g_set_prgname(). This name should not be localized, see the docs.

When a .desktop file is created this value helps with window grouping and desktop icons when the .desktop file's Name property differs form the executable's filename.

Name: ProgramName
Type: string

Debug​

This defines Debug specific options that apply to debug builds.

Name: Debug
Type: options.Debug

OpenInspectorOnStartup​

Setting this to true will open the WebInspector on startup of the application.

Name: OpenInspectorOnStartup
Type: bool

  1. This requires WebKit2GTK 2.36+ support and your app needs to be build with the build tag webkit2_36 to activate support for this feature. This also bumps the minimum requirement of WebKit2GTK to 2.36 for your app.↩
  2. This requires WebKit2GTK 2.40+ support and your app needs to be build with the build tag webkit2_40 to activate support for this feature. This also bumps the minimum requirement of WebKit2GTK to 2.40 for your app.↩