Tauri Syntax Events

tauri-syntax-events

Quick Reference

Rust Event Traits (Tauri 2.x)

Emitter Methods

Listener Methods

Frontend Event API (TypeScript)

TauriEvent Built-in Events

Critical Warnings

NEVER forget Clone on event payload structs — emit() requires Serialize + Clone. Omitting Clone causes a compile error that does not clearly indicate the source.

NEVER use special characters in event names — only alphanumeric, -, /, :, and _ are allowed. Other characters cause a runtime panic.

NEVER forget to call the unlisten function in frontend components — this causes memory leaks. In React, ALWAYS clean up in the useEffect return function.

NEVER forget to await the listen() call in TypeScript — listen() returns Promise<UnlistenFn>, not UnlistenFn directly.

ALWAYS import the Emitter trait (use tauri::Emitter;) before calling emit() in Rust — the method is not available without the trait import.

ALWAYS import the Listener trait (use tauri::Listener;) before calling listen() in Rust.

Essential Patterns

Pattern 1: Rust to Frontend (Emitter)

// Tauri 2.x — Broadcast from Rust to all frontend listeners
use tauri::Emitter;

#[derive(Clone, serde::Serialize)]
struct ProgressUpdate {
    task_id: String,
    percent: f64,
    message: String,
}

// In a command or setup hook:
app_handle.emit("progress", ProgressUpdate {
    task_id: "download-1".into(),
    percent: 45.5,
    message: "Downloading file...".into(),
})?;

Pattern 2: Frontend Listening

// Tauri 2.x — Listen in TypeScript
import { listen } from '@tauri-apps/api/event';

interface ProgressUpdate {
  taskId: string;
  percent: number;
  message: string;
}

const unlisten = await listen<ProgressUpdate>('progress', (event) => {
  console.log(`${event.payload.taskId}: ${event.payload.percent}%`);
});

// When done:
unlisten();

Pattern 3: Frontend to Rust (Emit + Listen)

// Tauri 2.x — Frontend emits
import { emit } from '@tauri-apps/api/event';

await emit('user-action', { action: 'save', documentId: 42 });

// Tauri 2.x — Rust listens (typically in setup hook)
use tauri::Listener;

app.listen("user-action", |event| {
    println!("User action: {:?}", event.payload());
});

Pattern 4: Targeted Emission

// Tauri 2.x — Emit to specific window
use tauri::Emitter;

app_handle.emit_to("main", "notification", "Update available")?;

// Emit with filter
app_handle.emit_filter("sync", payload, |target| {
    matches!(target, tauri::EventTarget::WebviewWindow { label } if label != "settings")
})?;

// Tauri 2.x — Frontend targeted emit
import { emitTo } from '@tauri-apps/api/event';

await emitTo('settings', 'config-changed', { key: 'theme', value: 'dark' });

Pattern 5: React Cleanup Pattern

// Tauri 2.x — Correct cleanup in React useEffect
import { listen } from '@tauri-apps/api/event';

useEffect(() => {
  let unlisten: (() => void) | undefined;

  listen<string>('update', (event) => {
    setState(event.payload);
  }).then((fn) => { unlisten = fn; });

  return () => {
    if (unlisten) unlisten();
  };
}, []);

Pattern 6: Once (Single-Fire Listener)

// Tauri 2.x — Rust: listen once, auto-removes
use tauri::Listener;

app.once("initialization-complete", |event| {
    println!("App initialized: {:?}", event.payload());
});

// Tauri 2.x — TypeScript: listen once
import { once } from '@tauri-apps/api/event';

await once<string>('app-ready', (event) => {
  console.log('App initialized:', event.payload);
});

TypeScript Event Types

type EventName = string; // alphanumeric, hyphens, slashes, colons, underscores
type EventCallback<T> = (event: Event<T>) => void;
type UnlistenFn = () => void;

interface Event<T> {
  event: EventName;
  id: number;
  payload: T;
}

interface Options {
  target?: string | EventTarget;
}

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

Permissions Required

Events require core:event:default in the capability file:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "windows": ["main"],
  "permissions": [
    "core:event:default"
  ]
}

Reference Links

• references/methods.md — Complete Emitter and Listener trait signatures
• references/examples.md — Working code examples for common event scenarios
• references/anti-patterns.md — What NOT to do, with WHY explanations

Official Sources

• https://v2.tauri.app/develop/calling-rust/#event-system
• https://docs.rs/tauri/2/tauri/trait.Emitter.html
• https://docs.rs/tauri/2/tauri/trait.Listener.html
• https://v2.tauri.app/reference/javascript/api/namespaceevent/