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.

Enumerations

TauriEvent

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L91

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

DRAG_DROP

DRAG_DROP: "tauri://drag-drop";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L141

The user dropped files onto a webview. See Webview.onDragDropEvent.

DRAG_ENTER

DRAG_ENTER: "tauri://drag-enter";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L137

The user dragged files onto a webview. See Webview.onDragDropEvent.

DRAG_LEAVE

DRAG_LEAVE: "tauri://drag-leave";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L143

The drag operation left the webview or was cancelled. See Webview.onDragDropEvent.

DRAG_OVER

DRAG_OVER: "tauri://drag-over";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L139

The user is moving dragged files over a webview. See Webview.onDragDropEvent.

WEBVIEW_CREATED

WEBVIEW_CREATED: "tauri://webview-created";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L135

A new webview was created.

WINDOW_BLUR

WINDOW_BLUR: "tauri://blur";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L106

A window lost focus. See Window.onFocusChanged.

WINDOW_CLOSE_REQUESTED

WINDOW_CLOSE_REQUESTED: "tauri://close-requested";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L100

The user requested a window to be closed (e.g. clicked the close button). See Window.onCloseRequested, which also handles preventing the close.

WINDOW_CREATED

WINDOW_CREATED: "tauri://window-created";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L115

A new window was created.

WINDOW_DESTROYED

WINDOW_DESTROYED: "tauri://destroyed";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L102

A window was destroyed, i.e. it is gone and its label can be reused.

WINDOW_FOCUS

WINDOW_FOCUS: "tauri://focus";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L104

A window gained focus. See Window.onFocusChanged.

WINDOW_MOVED

WINDOW_MOVED: "tauri://move";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L95

A window was moved. Payload: the new outer position, in physical pixels. See Window.onMoved.

WINDOW_RESIZED

WINDOW_RESIZED: "tauri://resize";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L93

A window was resized. Payload: the new inner size, in physical pixels. See Window.onResized.

WINDOW_RESUMED

WINDOW_RESUMED: "tauri://resumed";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L133

The window’s event loop was resumed after being suspended.

Platform-specific

• Android: emitted when the activity is resumed.
• Other platforms: never emitted.

WINDOW_SCALE_FACTOR_CHANGED

WINDOW_SCALE_FACTOR_CHANGED: "tauri://scale-change";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L111

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.

WINDOW_SUSPENDED

WINDOW_SUSPENDED: "tauri://suspended";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L124

The window’s event loop was suspended.

Platform-specific

• Android: emitted when the activity is paused.
• Other platforms: never emitted.

WINDOW_THEME_CHANGED

WINDOW_THEME_CHANGED: "tauri://theme-changed";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L113

The system or window theme changed. See Window.onThemeChanged.

Interfaces

Event

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L47

Type Parameters

Type Parameter
T

Properties

Property	Type	Description	Defined in
event	EventName	Event name	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L49
id	number	Event identifier used to unlisten	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L51
payload	T	Event payload	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L53

---

Options

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L63

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> }.	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L70

Type Aliases

EventCallback

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

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L56

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
event	Event<T>

Returns

void

---

EventName

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

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L61

---

EventTarget

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

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L39

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;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L59

Returns

void

Functions

emit()

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

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L267

Emits an event to all targets.

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>

Example

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

Since

1.0.0

---

emitTo()

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

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L289

Emits an event to all targets matching the given target.

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>

Example

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

Since

2.0.0

---

listen()

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

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L190

Listen to an emitted event to any target.

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.

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();

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,
   handler,
   options?
): Promise<UnlistenFn>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/event.ts#L238

Listens once to an emitted event to any target.

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.

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();

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