Skip to main content
Version: v2.0.0-beta.43

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"

func main() {

err := wails.Run(&options.App{
Title: "Menus Demo",
Width: 800,
Height: 600,
DisableResize: false,
Fullscreen: false,
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,
Assets: assets,
AssetsHandler: assetsHandler,
Menu: app.applicationMenu(),
Logger: nil,
LogLevel: logger.DEBUG,
LogLevelProduction: logger.ERROR,
OnStartup: app.startup,
OnDomReady: app.domready,
OnShutdown: app.shutdown,
OnBeforeClose: app.beforeClose,
WindowStartState: options.Maximised,
Bind: []interface{}{
app,
},
Windows: &windows.Options{
WebviewIsTransparent: false,
WindowIsTranslucent: false,
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
},
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,
},
})
if err != nil {
log.Fatal(err)
}
}

Titleโ€‹

Name: Title

Type: string

The text shown in the window's title bar.

Widthโ€‹

Name: Width

Type: int

The initial width of the window. Default: 1024.

Heightโ€‹

Name: Height

Type: int

The initial height of the window. Default: 768

DisableResizeโ€‹

Name: DisableResize

Type: bool

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

Fullscreenโ€‹

Name: Fullscreen

Type: bool

Setting this to true will make the window fullscreen at startup.

Framelessโ€‹

Name: Frameless

Type: bool

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

MinWidthโ€‹

Name: MinWidth

Type: int

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.

MinHeightโ€‹

Name: MinHeight

Type: int

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.

MaxWidthโ€‹

Name: MaxWidth

Type: int

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.

MaxHeightโ€‹

Name: MaxHeight

Type: int

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.

StartHiddenโ€‹

Name: StartHidden

Type: bool

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

HideWindowOnCloseโ€‹

Name: HideWindowOnClose

Type: bool

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

BackgroundColourโ€‹

Name: BackgroundColour

Type: *options.RGBA Example: options.NewRGBA(255,0,0,128) - Red at 50% transparency

This value is the default background colour of the window. Default: white

AlwaysOnTopโ€‹

Name: AlwaysOnTop

Type: bool

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

Assetsโ€‹

Name: Assets

Type: embed.FS

The frontend assets to be used by the application. Requires an index.html file.

AssetsHandlerโ€‹

Name: AssetsHandler

Type: http.Handler

The assets handler is a generic http.Handler which will be called for any non GET request on the assets server and for GET requests which can not be served from the assets because the file is not found.

ValueWinMacLin
GETโœ…โœ…โœ…
POSTโœ…โœ…โŒ
PUTโœ…โœ…โŒ
PATCHโœ…โœ…โŒ
DELETEโœ…โœ…โŒ
Request Headersโœ…โœ…โŒ
Request Bodyโœ…โœ…โŒ
Request Body StreamingโŒโŒโŒ
Response StatusCodesโœ…โœ…โŒ
Response Headersโœ…โœ…โŒ
Response Bodyโœ…โœ…โœ…
Response Body StreamingโŒโŒโœ…

NOTE: Linux is currently very limited due to targeting a WebKit2GTK Version < 2.36.0. In the future some features will be supported by the introduction of WebKit2GTK 2.36.0+ support.

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: Menu

Type: *menu.Menu

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.

Loggerโ€‹

Name: Logger

Type: logger.Logger

Default: Logger to Stdout

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

LogLevelโ€‹

Name: LogLevel

Type: logger.LogLevel

Default: Info in dev mode, Error in production mode

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

LogLevelProductionโ€‹

Name: LogLevelProduction

Type: logger.LogLevel

Default: Error

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

OnStartupโ€‹

Name: OnStartup

Type: func(ctx context.Context)

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

OnDomReadyโ€‹

Name: OnDomReady

Type: func(ctx context.Context)

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

OnShutdownโ€‹

Name: OnShutdown

Type: func(ctx context.Context)

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

OnBeforeCloseโ€‹

Name: OnBeforeClose

Type: func(ctx context.Context) bool

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"
}

WindowStartStateโ€‹

Name: WindowStartState

Type: options.WindowStartState

Defines how the window should present itself at startup.

ValueWinMacLin
Fullscreenโœ…โœ…โœ…
Maximisedโœ…โœ…โœ…
Minimisedโœ…โŒโœ…

Bindโ€‹

Name: Bind

Type: []interface{}

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

Windowsโ€‹

Name: Windows

Type: *windows.Options

This defines Windows specific options.

Macโ€‹

Name: Mac

Type: *mac.Options

This defines Mac specific options.

Linuxโ€‹

Name: Linux

Type: *linux.Options

This defines Linux specific options.

Windows Specific Optionsโ€‹

WebviewIsTransparentโ€‹

Name: WebviewIsTransparent

Type: bool

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.

WindowIsTranslucentโ€‹

Name: WindowIsTranslucent

Type: bool

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

DisableWindowIconโ€‹

Name: DisableWindowIcon

Type: bool

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

DisableFramelessWindowDecorationsโ€‹

Name: DisableFramelessWindowDecorations

Type: bool

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.

WebviewUserDataPathโ€‹

Name: WebviewUserDataPath

Type: string

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

WebviewBrowserPathโ€‹

Name: WebviewBrowserPath

Type: string

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:

Themeโ€‹

Name: Theme

Type: windows.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

CustomThemeโ€‹

Name: CustomTheme

Type: windows.CustomTheme

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.

CustomThemeโ€‹

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โ€‹

Name: Messages

Type: *windows.Messages

A struct of strings used by the webview2 installer if a valid webview2 runtime is not found. Customise this for any language you choose to support.

ResizeDebounceMSโ€‹

Name: ResizeDebounceMS

Type: uint16

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.

OnSuspendโ€‹

Name: OnSuspend

Type: func()

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

OnResumeโ€‹

Name: OnResume

Type: func()

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

Mac Specific Optionsโ€‹

TitleBarโ€‹

Name: TitleBar

Type: *mac.TitleBar

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

Appearanceโ€‹

Name: Appearance

Type: AppearanceType

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

WebviewIsTransparentโ€‹

Name: WebviewIsTransparent

Type: bool

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.

WindowIsTranslucentโ€‹

Name: WindowIsTranslucent

Type: bool

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

Aboutโ€‹

Name: About

Type: 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.

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 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,
}

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 Specific Optionsโ€‹

Iconโ€‹

Name: Icon

Type: []byte

Sets up the icon representing the window. This icon is used when the window is minimized (also known as iconified). 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.