wails/mkdocs-website/docs/en/API/events.md

Events

Event Hooks

--8<-- ./docs/en/API/event_hooks.md --8<--

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.

=== "Go" ```go 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")
```

=== "JS" ```javascript 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() {}