@tauri-apps/api/event

The event system allows you to emit events to the backend and listen to events from it.

This package is also accessible with window.__TAURI__.event when app.withGlobalTauri in tauri.conf.json is set to true.

Remarks

All commands used by this module (core:event:allow-listen, allow-unlisten, allow-emit and allow-emit-to) are part of the core:event:default permission set, which is enabled by default, so no extra capability configuration is needed.

Functions

emit()

function emit<T>(event: string, payload?: T): Promise<void>;

Defined in: packages/api/src/event.ts:267

Emits an event to all targets.

Example

import { emit } from '@tauri-apps/api/event';
await emit('frontend-loaded', { loggedIn: true, token: 'authToken' });

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
event	string	Event name. Must include only alphanumeric characters, -, /, : and _.
payload?	T	Event payload.

Returns

Promise<void>

Since

1.0.0

---

emitTo()

function emitTo<T>(
   target: string | EventTarget,
   event: string,
   payload?: T
): Promise<void>;

Defined in: packages/api/src/event.ts:289

Emits an event to all targets matching the given target.

Example

import { emitTo } from '@tauri-apps/api/event';
await emitTo('main', 'frontend-loaded', { loggedIn: true, token: 'authToken' });

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
target	| string | EventTarget	Label of the target Window/Webview/WebviewWindow or raw EventTarget object.
event	string	Event name. Must include only alphanumeric characters, -, /, : and _.
payload?	T	Event payload.

Returns

Promise<void>

Since

2.0.0

---

listen()

function listen<T>(
   event: EventName,
   handler: EventCallback<T>,
   options?: Options
): Promise<UnlistenFn>;

Defined in: packages/api/src/event.ts:190

Listen to an emitted event to any target.

Example

import { listen } from '@tauri-apps/api/event';
const unlisten = await listen<string>('error', (event) => {
  console.log(`Got error, payload: ${event.payload}`);
});

// call unlisten when your handler goes out of scope e.g. the component is unmounted
unlisten();

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
event	EventName	Event name. Must include only alphanumeric characters, -, /, : and _.
handler	EventCallback<T>	Event handler callback.
options?	Options	Event listening options.

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event.

Remarks

Listeners bound to a window or webview are removed automatically when that window or webview is destroyed, so you do not need to unlisten just to avoid leaking across a window close. You should still call the returned function when the listener’s own scope ends — for example on page navigation or when a component unmounts — otherwise the handler keeps running for the lifetime of the webview.

Since

1.0.0

---

once()

function once<T>(
   event: EventName,
   handler: EventCallback<T>,
   options?: Options
): Promise<UnlistenFn>;

Defined in: packages/api/src/event.ts:238

Listens once to an emitted event to any target.

Example

import { once } from '@tauri-apps/api/event';
interface LoadedPayload {
  loggedIn: boolean,
  token: string
}
const unlisten = await once<LoadedPayload>('loaded', (event) => {
  console.log(`App is loaded, loggedIn: ${event.payload.loggedIn}, token: ${event.payload.token}`);
});

// call unlisten when your handler goes out of scope e.g. the component is unmounted
unlisten();

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
event	EventName	Event name. Must include only alphanumeric characters, -, /, : and _.
handler	EventCallback<T>	Event handler callback.
options?	Options	Event listening options.

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event.

Remarks

The listener removes itself after the first event, and listeners bound to a window or webview are also removed automatically when that target is destroyed. Still call the returned function when the listener’s own scope ends before the event arrives — for example on page navigation or component unmount.

Since

1.0.0

Enumerations

TauriEvent

Defined in: packages/api/src/event.ts:91

The built-in event names emitted by Tauri itself.

These are the raw names behind the on* helpers of the Window and Webview classes (e.g. Window.onResized listens to TauriEvent.WINDOW_RESIZED). Prefer those helpers when one exists, since they also decode the payload into the matching class (PhysicalSize, PhysicalPosition, …).

Example

import { listen, TauriEvent } from '@tauri-apps/api/event';
const unlisten = await listen(TauriEvent.WINDOW_DESTROYED, (event) => {
  console.log('a window was destroyed', event.payload);
});

Since

1.1.0

Enumeration Members

Enumeration Member	Value	Description	Defined in
DRAG_DROP	"tauri://drag-drop"	The user dropped files onto a webview. See Webview.onDragDropEvent.	packages/api/src/event.ts:141
DRAG_ENTER	"tauri://drag-enter"	The user dragged files onto a webview. See Webview.onDragDropEvent.	packages/api/src/event.ts:137
DRAG_LEAVE	"tauri://drag-leave"	The drag operation left the webview or was cancelled. See Webview.onDragDropEvent.	packages/api/src/event.ts:143
DRAG_OVER	"tauri://drag-over"	The user is moving dragged files over a webview. See Webview.onDragDropEvent.	packages/api/src/event.ts:139
WEBVIEW_CREATED	"tauri://webview-created"	A new webview was created.	packages/api/src/event.ts:135
WINDOW_BLUR	"tauri://blur"	A window lost focus. See Window.onFocusChanged.	packages/api/src/event.ts:106
WINDOW_CLOSE_REQUESTED	"tauri://close-requested"	The user requested a window to be closed (e.g. clicked the close button). See Window.onCloseRequested, which also handles preventing the close.	packages/api/src/event.ts:100
WINDOW_CREATED	"tauri://window-created"	A new window was created.	packages/api/src/event.ts:115
WINDOW_DESTROYED	"tauri://destroyed"	A window was destroyed, i.e. it is gone and its label can be reused.	packages/api/src/event.ts:102
WINDOW_FOCUS	"tauri://focus"	A window gained focus. See Window.onFocusChanged.	packages/api/src/event.ts:104
WINDOW_MOVED	"tauri://move"	A window was moved. Payload: the new outer position, in physical pixels. See Window.onMoved.	packages/api/src/event.ts:95
WINDOW_RESIZED	"tauri://resize"	A window was resized. Payload: the new inner size, in physical pixels. See Window.onResized.	packages/api/src/event.ts:93
WINDOW_RESUMED	"tauri://resumed"	The window’s event loop was resumed after being suspended. Platform-specific - Android: emitted when the activity is resumed. - Other platforms: never emitted.	packages/api/src/event.ts:133
WINDOW_SCALE_FACTOR_CHANGED	"tauri://scale-change"	The scale factor of the monitor a window is on changed, or the window moved to a monitor with a different scale factor. See Window.onScaleChanged.	packages/api/src/event.ts:111
WINDOW_SUSPENDED	"tauri://suspended"	The window’s event loop was suspended. Platform-specific - Android: emitted when the activity is paused. - Other platforms: never emitted.	packages/api/src/event.ts:124
WINDOW_THEME_CHANGED	"tauri://theme-changed"	The system or window theme changed. See Window.onThemeChanged.	packages/api/src/event.ts:113

Interfaces

Event

Defined in: packages/api/src/event.ts:47

Type Parameters

Type Parameter
T

Properties

Property	Type	Description	Defined in
event	EventName	Event name	packages/api/src/event.ts:49
id	number	Event identifier used to unlisten	packages/api/src/event.ts:51
payload	T	Event payload	packages/api/src/event.ts:53

---

Options

Defined in: packages/api/src/event.ts:63

Properties

Property	Type	Description	Defined in
target?	| string | EventTarget	The event target to listen to, defaults to { kind: 'Any' }, see EventTarget. If a string is provided, it is used as the label of an AnyLabel target, i.e. { kind: 'AnyLabel', label: <the string> }.	packages/api/src/event.ts:70

Type Aliases

EventCallback

type EventCallback<T> = (event: Event<T>) => void;

Defined in: packages/api/src/event.ts:56

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
event	Event<T>

Returns

void

---

EventName

type EventName =
  | `${TauriEvent}`
| string & Record<never, never>;

Defined in: packages/api/src/event.ts:61

---

EventTarget

type EventTarget =
  | {
  kind: "Any";
}
  | {
  kind: "AnyLabel";
  label: string;
}
  | {
  kind: "App";
}
  | {
  kind: "Window";
  label: string;
}
  | {
  kind: "Webview";
  label: string;
}
  | {
  kind: "WebviewWindow";
  label: string;
};

Defined in: packages/api/src/event.ts:39

The target of an event, used to filter which listeners receive it and which listeners a given emit reaches.

• Any: matches every target (the default).
• AnyLabel: matches any window, webview or webview window with the given label.
• App: the application itself, i.e. listeners registered with app.listen on the Rust side.
• Window / Webview / WebviewWindow: the specific target with that label.

Since

2.0.0

---

UnlistenFn

type UnlistenFn = () => void;

Defined in: packages/api/src/event.ts:59

Returns

void