Skip to content

Events#

Event Hooks#

wails3 provides an event system that allows for hooking into application and window events

// Notification of application start
application.RegisterApplicationEventHook(events.Common.ApplicationStarted, func(event *application.ApplicationEvent) {
    app.Logger.Info("Application started!")
})

// Notification of system theme change
application.OnApplicationEvent(events.Common.ThemeChanged, func(event *application.ApplicationEvent) {
    app.Logger.Info("System theme changed!")
    if event.Context().IsDarkMode() {
        app.Logger.Info("System is now using dark mode!")
    } else {
        app.Logger.Info("System is now using light mode!")
    }
})

// Disable window closing by canceling the event
window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    app.Logger.Info("Window 1 Closing? Nope! Not closing!")
    e.Cancel()
})

// Notification of window focus
window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("[ApplicationEvent] Window focus!")
})

Application Events#

Application events are hookable events that can be registered with application.RegisterApplicationEventHook() and application.OnApplicationEvent(). These events are based on events.ApplicationEventType.

events.Common.ApplicationStarted
Triggered when the application starts
events.Common.ThemeChanged
Triggered when the application theme changes

Window Events#

events.Common.WindowMaximised
Triggered when the window is maximised
events.Common.WindowUnmaximised
Triggered when the window is unmaximised
events.Common.WindowMinimised
Triggered when the window is minimised
events.Common.WindowUnminimised
Triggered when the window is unminimised
events.Common.WindowFullscreen
Triggered when the window is set to fullscreen
events.Common.WindowUnfullscreen
Triggered when the window is unfullscreened
events.Common.WindowRestored
Triggered when the window is restored
events.Common.WindowClosing
Triggered before the window closes
events.Common.WindowZoom
Triggered when the window is zoomed
events.Common.WindowZoomOut
Triggered when the window is zoomed out
events.Common.WindowZoomIn
Triggered when the window is zoomed in
events.Common.WindowZoomReset
Triggered when the window zoom is reset
events.Common.WindowFocus
Triggered when the window gains focus
events.Common.WindowLostFocus
Triggered when the window loses focus
events.Common.WindowShow
Triggered when the window is shown
events.Common.WindowHide
Triggered when the window is hidden
events.Common.WindowDPIChanged
Triggered when the window DPI changes
events.Common.WindowFilesDropped
Triggered when files are dropped on the window
events.Common.WindowRuntimeReady
Triggered when the window runtime is ready
events.Common.WindowDidMove
Triggered when the window is moved
events.Common.WindowDidResize
Triggered when the window is resized

OS-Specific Events#

Linux Events#

Application Events#
events.Linux.ApplicationStartup
Triggered when the application starts
events.Linux.SystemThemeChanged
Triggered when the system theme changes
Window Events#
events.Linux.WindowLoadChanged
Triggered when the window load changes
events.Linux.WindowDeleteEvent
Triggered when the window is deleted
events.Linux.WindowDidMove
Triggered when the window is moved
events.Linux.WindowDidResize
Triggered when the window is resized
events.Linux.WindowFocusIn
Triggered when the window gains focus
events.Linux.WindowFocusOut
Triggered when the window loses focus

Windows Events#

Application Events#
events.Windows.ApplicationStarted
Triggered when the application starts
events.Windows.SystemThemeChanged
Triggered when the system theme changes
events.Windows.APMPowerStatusChange
Triggered when the system power status changes
events.Windows.APMSuspend
Triggered when the system suspends
events.Windows.APMResumeAutomatic
Triggered when the system resumes after a sleep
events.Windows.APMResumeSuspend
Triggered when the system resumes after a suspend and resume was triggered by the user
Window Events#
events.Windows.WebviewNavigationCompleted
Triggered when the webview navigation is completed
events.Windows.WindowInactive
Triggered when the window is inactive
events.Windows.WindowActive
Triggered when the window is active
events.Windows.ClickActive
Triggered when the window is activated via a click
events.Windows.MaximiseActive
Triggered when the window is maximised
events.Windows.UnMaximise
Triggered when the window is unmaximised
events.Windows.Fullscreen
Triggered when the window is set to fullscreen
events.Windows.UnFullscreen
Triggered when the window is exited from fullscreene
events.Windows.WindowRestore
Triggered when the window is restored
events.Windows.WindowMinimise
Triggered when the window is minimised
events.Windows.WindowUnminimise
Triggered when the window is unminimised
events.Windows.WindowClose
Triggered before the window closes
events.Windows.WindowSetFocus
Triggered when the window gains keyboard focus
events.Windows.WindowKillFocus
Triggered when the window loses keyboard focus
events.Windows.WindowDragDrop
Triggered when files are dropped on the window
events.Windows.WindowDragEnter
Triggered when a drag enters the window
events.Windows.WindowDragLeave
Triggered when a drag leaves the window
events.Windows.WindowDragOver
Triggered when a drag is over the window
events.Windows.WindowDidMove
Triggered after a window has moved

macOS Events#

Application Events#
events.Mac.ApplicationDidBecomeActive
Triggered when the application becomes active
events.Mac.ApplicationDidChangeBackingProperties
Triggered when the application changes backing properties
events.Mac.ApplicationDidChangeEffectiveAppearance
Triggered when the application changes effective appearance
events.Mac.ApplicationDidChangeIcon
Triggered when the application changes icon
events.Mac.ApplicationDidChangeOcclusionState
Triggered when the application changes occlusion state
events.Mac.ApplicationDidChangeScreenParameters
Triggered when the application changes screen parameters
events.Mac.ApplicationDidChangeStatusBarFrame
Triggered when the application changes status bar frame
events.Mac.ApplicationDidChangeStatusBarOrientation
Triggered when the application changes status bar orientation
events.Mac.ApplicationDidFinishLaunching
Triggered when the application finishes launching
events.Mac.ApplicationDidResignActiveNotification
Triggered when the application is no longer active
events.Mac.ApplicationDidHide
Triggered when the application is hidden
events.Mac.ApplicationDidUpdate
Triggered when the application updates
events.Mac.ApplicationWillBecomeActive
Triggered when the application is about to become active
events.Mac.ApplicationWillFinishLaunching
Triggered when the application is about to finish launching
events.Mac.ApplicationWillHide
Triggered when the application is about to hide
events.Mac.ApplicationWillResignActive
Triggered when the application is about to lose focus
events.Mac.ApplicationWillTerminate
Triggered when the application is about to terminate
events.Mac.ApplicationWillUnhide
Triggered when the application is about to unhide
events.Mac.ApplicationWillUpdate
Triggered when the application is about to update
events.Mac.ApplicationDidChangeTheme
Triggered when the application changes theme
events.Mac.MenuWillOpen
Triggered when the menu is about to open
events.Mac.MenuDidOpen
Triggered when the menu opens
events.Mac.MenuDidClose
Triggered when the menu closes
events.Mac.MenuWillSendAction
Triggered when the menu is about to send an action
events.Mac.MenuDidSendAction
Triggered when the menu sends an action
events.Mac.MenuWillHighlightItem
Triggered when the menu is about to highlight an item
events.Mac.MenuDidHighlightItem
Triggered when the menu highlights an item
events.Mac.MenuWillDisplayItem
Triggered when the menu is about to display an item
events.Mac.MenuDidDisplayItem
Triggered when the menu displays an item
events.Mac.MenuWillAddItem
Triggered when the menu is about to add an item
events.Mac.MenuDidAddItem
Triggered when the menu adds an item
events.Mac.MenuWillRemoveItem
Triggered when the menu is about to remove an item
events.Mac.MenuDidRemoveItem
Triggered when the menu removes an item
events.Mac.MenuWillBeginTracking
Triggered when the menu is about to begin tracking
events.Mac.MenuDidBeginTracking
Triggered when the menu begins tracking
events.Mac.MenuWillEndTracking
Triggered when the menu is about to end tracking
events.Mac.MenuDidEndTracking
Triggered when the menu ends tracking
events.Mac.MenuWillUpdate
Triggered when the menu is about to update
events.Mac.MenuDidUpdate
Triggered when the menu updates
events.Mac.MenuWillPopUp
Triggered when the menu is about to pop up
events.Mac.MenuDidPopUp
Triggered when the menu pops up
events.Mac.MenuWillSendActionToItem
Triggered when the menu is about to send an action to an item
events.Mac.MenuDidSendActionToItem
Triggered when the menu sends an action to an item
Window Events#
events.Mac.WindowDidBecomeKey
Triggered when the window becomes key
events.Mac.WindowDidBecomeMain
Triggered when the window becomes main
events.Mac.WindowDidBeginSheet
Triggered when the window begins a sheet
events.Mac.WindowDidChangeAlpha
Triggered when the window alpha changes
events.Mac.WindowDidChangeBackingLocation
Triggered when the window backing location changes
events.Mac.WindowDidChangeBackingProperties
Triggered when the window backing properties change
events.Mac.WindowDidChangeCollectionBehavior
Triggered when the window collection behavior changes
events.Mac.WindowDidChangeEffectiveAppearance
Triggered when the window effective appearance changes
events.Mac.WindowDidChangeOcclusionState
Triggered when the window occlusion state changes
events.Mac.WindowDidChangeOrderingMode
Triggered when the window ordering mode changes
events.Mac.WindowDidChangeScreen
Triggered when the window screen changes
events.Mac.WindowDidChangeScreenParameters
Triggered when the window screen parameters change
events.Mac.WindowDidChangeScreenProfile
Triggered when the window screen profile changes
events.Mac.WindowDidChangeScreenSpace
Triggered when the window screen space changes
events.Mac.WindowDidChangeScreenSpaceProperties
Triggered when the window screen space properties change
events.Mac.WindowDidChangeSharingType
Triggered when the window sharing type changes
events.Mac.WindowDidChangeSpace
Triggered when the window space changes
events.Mac.WindowDidChangeSpaceOrderingMode
Triggered when the window space ordering mode changes
events.Mac.WindowDidChangeTitle
Triggered when the window title changes
events.Mac.WindowDidChangeToolbar
Triggered when the window toolbar changes
events.Mac.WindowDidChangeVisibility
Triggered when the window visibility changes
events.Mac.WindowDidDeminiaturize
Triggered when the window is deminiaturized
events.Mac.WindowDidEndSheet
Triggered when the window ends a sheet
events.Mac.WindowDidEnterFullScreen
Triggered when the window enters fullscreen
events.Mac.WindowDidEnterVersionBrowser
Triggered when the window enters version browser
events.Mac.WindowDidExitFullScreen
Triggered when the window exits fullscreen
events.Mac.WindowDidExitVersionBrowser
Triggered when the window exits version browser
events.Mac.WindowDidExpose
Triggered when the window is exposed
events.Mac.WindowDidFocus
Triggered when the window is focused
events.Mac.WindowDidMiniaturize
Triggered when the window is miniaturized
events.Mac.WindowDidMove
Triggered when the window is moved
events.Mac.WindowDidOrderOffScreen
Triggered when the window is ordered off-screen
events.Mac.WindowDidOrderOnScreen
Triggered when the window is ordered on screen
events.Mac.WindowDidResignKey
Triggered when the window resigns key
events.Mac.WindowDidResignMain
Triggered when the window resigns main
events.Mac.WindowDidResize
Triggered when the window is resized
events.Mac.WindowDidUpdate
Triggered when the window updates
events.Mac.WindowDidUpdateAlpha
Triggered when the window alpha updates
events.Mac.WindowDidUpdateCollectionBehavior
Triggered when the window collection behavior updates
events.Mac.WindowDidUpdateCollectionProperties
Triggered when the window collection properties update
events.Mac.WindowDidUpdateShadow
Triggered when the window shadow updates
events.Mac.WindowDidUpdateTitle
Triggered when the window title updates
events.Mac.WindowDidUpdateToolbar
Triggered when the window toolbar updates
events.Mac.WindowDidUpdateVisibility
Triggered when the window visibility updates
events.Mac.WindowShouldClose
Triggered when the window should close
events.Mac.WindowWillBecomeKey
Triggered when the window will become key
events.Mac.WindowWillBecomeMain
Triggered when the window will become main
events.Mac.WindowWillBeginSheet
Triggered when the window will begin a sheet
events.Mac.WindowWillChangeOrderingMode
Triggered when the window will change ordering mode
events.Mac.WindowWillClose
Triggered when the window will close
events.Mac.WindowWillDeminiaturize
Triggered when the window will deminiaturize
events.Mac.WindowWillEnterFullScreen
Triggered when the window will enter fullscreen
events.Mac.WindowWillEnterVersionBrowser
Triggered when the window will enter version browser
events.Mac.WindowWillExitFullScreen
Triggered when the window will exit fullscreen
events.Mac.WindowWillExitVersionBrowser
Triggered when the window will exit version browser
events.Mac.WindowWillFocus
Triggered when the window will focus
events.Mac.WindowWillMiniaturize
Triggered when the window will miniaturize
events.Mac.WindowWillMove
Triggered when the window will move
events.Mac.WindowWillOrderOffScreen
Triggered when the window will order off-screen
events.Mac.WindowWillOrderOnScreen
Triggered when the window will order on screen`
events.Mac.WindowWillResignMain
Triggered when the window will resign main
events.Mac.WindowWillResize
Triggered when the window will resize
events.Mac.WindowWillUnfocus
Triggered when the window will unfocus`
events.Mac.WindowWillUpdate
Triggered when the window will update
events.Mac.WindowWillUpdateAlpha
Triggered when the window will update alpha
events.Mac.WindowWillUpdateCollectionBehavior
Triggered when the window will update collection behavior
events.Mac.WindowWillUpdateCollectionProperties
Triggered when the window will update collection properties
events.Mac.WindowWillUpdateShadow
Triggered when the window will update shadow
events.Mac.WindowWillUpdateTitle
Triggered when the window will update title
events.Mac.WindowWillUpdateToolbar
Triggered when the window will update toolbar
events.Mac.WindowWillUpdateVisibility
Triggered when the window will update visibility
events.Mac.WindowWillUseStandardFrame
Triggered when the window will use standard frame
events.Mac.WebviewDidStartProvisionalNavigation
Triggered when the webview starts a provisional navigation
events.Mac.WebviewDidReceiveServerRedirectForProvisionalNavigation
Triggered when the webview receives a server redirect for a provisional navigation
events.Mac.WebviewDidFinishNavigation
Triggered when the webview finishes navigation
events.Mac.WebviewDidCommitNavigation
Triggered when the webview commits navigation
events.Mac.WindowFileDraggingEntered
Triggered when files are dragged into the window`
events.Mac.WindowFileDraggingPerformed
Triggered when files are dragged in the window
events.Mac.WindowFileDraggingExited
Triggered when files are dragged out of the window

Custom Events#

You can create your own custom events that can be emitted and received on both the frontend and backend. Events are able to emitted at both the application and the window level. The receiver of the event gets data of where the event was emitted from along with the data that was sent with the event. Events can be cancelled by the receiver.

app.OnEvent("event1", func(e *application.CustomEvent) {
    app.Logger.Info("[Go] CustomEvent received", "name", e.Name, "data", e.Data, "sender", e.Sender, "cancelled", e.Cancelled)
    app.Logger.Info("[Go]", e.Data[0].(string)) // Logs "Hello from JS" to the terminal
})

window.EmitEvent("event2", "Hello from Go")

wails.Events.Emit("event1", "Hello from JS")

wails.Events.On("event2", function(event) {
    console.log("[JS] CustomEvent received", event)
    console.log(event.data) // prints "Hello from Go" to the webview console
})

Emitting Events#

application.EmitEvent(name string, data ...any)
Emits an event from the application instance
window.EmitEvent(name string, data ...any)
Emits an event from the window instance
wails.Events.Emit(event:wails.Events.EventData)
Emits an event from the frontend sending an object with name and data properties or the typescript type WailsEvent

Receiving Events#

Events can be received on the application instance and the frontend with a couple options of how you chose to receive them. You can register a single event listener that will trigger every time the event is emitted or you can register an event listener that will only trigger a specific number of times.

Golang

application.OnEvent(name string, handler func(data ...any))
Registers an event on the application instance this will trigger every time the event is emitted
application.OnMultipleEvent(name string, handler func(data ...any), count int)
Registers an event on the application instance this will trigger every time the event is emitted up to the count specified

Frontend

wails.Events.On(name: string, callback: ()=>void),
Registers an event on the frontend, this function returns a function that can be called to remove the event listener
wails.Events.Once(name: string, callback: ()=>void),
Registers an event on the frontend that will only be called once, this function returns a function that can be called to remove the event listener
wails.Events.OnMultiple(name: string, callback: ()=>void, count: number),
Registers an event on the frontend that will only be called count times, this function returns a function that can be called to remove the event listener

Removing Events#

There are a few ways to remove events that are registered. All of the registration functions return a function that can be called to remove the event listeneer in the frontend. There are additional functions provided to help remove events as well.

Golang

application.OffEvent(name string, ...additionalNames string)
Removes an event listener with the specificed name
application.ResetEvents()
Removes all registered events and hooks

Frontend

wails.Events.OffAll()
Removes all registered events
wails.Events.Off(name: string)
Removes an event listener with the specified name

Event Types#

ApplicationEvent#

Returned when an application hook event is triggered. The event can be cancelled by calling the Cancel() method on the event. 

type ApplicationEvent struct {
  Id        uint
  ctx       *ApplicationEventContext
  Cancelled bool
}

// Cancel the event
func (a *ApplicationEvent) Cancel() {}

WindowEvent#

Returned when a window hook event is triggered. The event can be cancelled by calling the Cancel() method on the event. 

type WindowEvent struct {
    ctx       *WindowEventContext
    Cancelled bool
}

// Cancel the event
func (w *WindowEvent) Cancel() {}

CustomEvent#

CustomEvent is returned when an event is being recieved it includes the name of the event, the data that was sent with the event, the sender of the event, application or a specific window. The event can be cancelled by calling the Cancel() method on the event. 

type CustomEvent struct {
    Name      string `json:"name"`
    Data      any    `json:"data"`
    Sender    string `json:"sender"`
    Cancelled bool
}

// Cancel the event
func (c *CustomEvent) Cancel() {}