desktop-multiwindow-tauri
Tauri 2.x multi-window creation, event system, window state persistence, parent/child and modal windows
Install
npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/desktop-multiwindow-tauri/skills/desktop-multiwindow-tauri
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
git clone https://github.com/agents-inc/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Tauri Multi-Window & Events
Quick Guide: Create windows from JS with
new WebviewWindow(label, options)or from Rust withWebviewWindowBuilder. Communicate across windows using events:emit()broadcasts globally,emitTo(label, event, payload)targets a specific window,emit_filter()targets multiple windows by predicate. Always call the unlisten function returned bylisten(). Usetauri-plugin-window-stateto persist window position/size across sessions. Window labels must be unique and are used for both event targeting and permission scoping.Current version: Tauri 2.x (stable). Multi-webview in a single window requires the
unstablefeature flag.
<critical_requirements>
CRITICAL: Before Using This Skill
(You MUST give every window a unique label -- labels identify windows for event targeting, permissions, and retrieval)
(You MUST always call the unlisten function returned by listen() / once() -- leaked listeners cause memory leaks in long-running apps)
(You MUST check if a window already exists before creating it -- duplicate labels cause runtime errors)
(You MUST add window labels to capability file windows array -- windows without permissions cannot use plugins or core APIs)
(You MUST use @tauri-apps/api/event for global events and @tauri-apps/api/webviewWindow for window-scoped events -- mixing them causes missed events)
</critical_requirements>
Auto-detection: WebviewWindow, WebviewWindowBuilder, emit_to, emitTo, emit_filter, EventTarget, window label, multi-window, onCloseRequested, tauri-plugin-window-state, parent window, modal window, WebviewBuilder, add_child, getCurrentWebviewWindow, window.listen, window.emit, cross-window communication
When to use:
- Creating secondary windows (settings, preferences, about, detached panels)
- Communicating between windows via the Tauri event system
- Handling window close confirmation (unsaved changes dialogs)
- Persisting window size/position across app restarts
- Setting up parent/child or modal window relationships
- Building multi-panel layouts with multiple webviews in a single window
When NOT to use:
- Single-window apps with no inter-window communication (use the base Tauri framework skill)
- General Tauri commands, IPC, or plugin setup (use the base Tauri framework skill)
- Frontend framework state management within a single window (use respective framework skills)
Key patterns covered:
- Window creation from JS and Rust (examples/core.md)
- Event system: emit, emitTo, emit_filter for targeted messaging (examples/core.md)
- Cross-window state synchronization via events (examples/core.md)
- Window close confirmation with onCloseRequested (examples/core.md)
- Window state persistence with tauri-plugin-window-state (examples/persistence.md)
- Parent/child windows and modal dialogs (examples/advanced.md)
- Multi-webview in a single window (unstable) (examples/advanced.md)
Detailed resources:
- examples/core.md - Window creation, event system, close confirmation, cross-window sync
- examples/persistence.md - Window state plugin setup, manual save/restore, StateFlags
- examples/advanced.md - Parent/child windows, modals, multi-webview layouts
- reference.md - API quick reference, event method comparison, decision framework
<decision_framework>
Decision Framework
Event Targeting
Who should receive this event?
|-- ALL windows in the app?
| +-- emit() (global broadcast)
|-- ONE specific window?
| +-- emitTo(label, event, payload) (targeted)
|-- MULTIPLE specific windows (but not all)?
| +-- emit_filter() with predicate (Rust only)
+-- The backend (Rust side)?
+-- emit() from frontend + app.listen() in Rust
Window Architecture
Does this UI surface need to be a separate window?
|-- Is it a settings/preferences panel?
| +-- YES: separate window with its own label
|-- Is it a modal confirmation dialog?
| +-- YES: child window with parent set
|-- Is it a dockable/undockable panel (IDE-style)?
| +-- YES: multi-webview in single window (unstable)
|-- Is it content that can live in the same DOM?
| +-- NO: don't create a new window -- use in-app routing/tabs
+-- Does it need to persist across window close?
+-- YES: use tauri-plugin-window-state
Where to Create Windows
Where does window creation belong?
|-- Triggered by user action in UI (button click)?
| +-- Frontend: new WebviewWindow(label, options)
|-- Triggered by backend logic (file watcher, system event)?
| +-- Rust: WebviewWindowBuilder::new(app, label, url)
|-- Need multiple webviews in one window?
| +-- Rust: WindowBuilder + window.add_child(WebviewBuilder)
+-- Declared at startup in config?
+-- tauri.conf.json "windows" array
See reference.md for the complete API quick reference.
</decision_framework>
<red_flags>
RED FLAGS
High Priority Issues:
- Duplicate window labels -- creating a window with a label that already exists throws a runtime error; always check first with
getByLabel()orapp.get_webview_window() - Missing unlisten calls --
listen()returns an unlisten function; not calling it leaks memory, especially in long-running apps or components that mount/unmount - Window label not in capability file
windowsarray -- the new window silently lacks permissions for plugins and core APIs - Using
@tauri-apps/api/taurifor event imports -- removed in v2; use@tauri-apps/api/eventfor global events and@tauri-apps/api/webviewWindowfor window-scoped events - Calling
emit()when you meanemitTo()-- broadcasting sensitive events (auth tokens, user data) to all windows is a security risk
Medium Priority Issues:
- Not handling
tauri://errorevent on window creation -- creation can fail silently without this listener - Using
close()afterpreventDefault()in close handler -- triggers the close-requested event again; usedestroy()to force-close without re-triggering - Hardcoding window dimensions without named constants -- magic numbers make layouts harder to maintain
- Not using
center: trueor explicit position -- windows appear at OS-default position, which may be off-screen on multi-monitor setups
Gotchas & Edge Cases:
onCloseRequestedon dynamic windows: there is a known issue whereevent.preventDefault()may not work on windows created at runtime; use the Ruston_window_eventapproach as a fallback- Event payload serialization: payloads must be serializable (JSON-compatible from JS,
serde::Serializefrom Rust); complex types like functions or DOM nodes cannot be sent - Window labels: must be alphanumeric with
-,/,:,_characters only -- no spaces or special characters - Multi-monitor:
center()centers on the primary monitor; for specific monitor positioning usesetPosition()withPhysicalPosition emit_filteris Rust-only: there is no JavaScript equivalent; use multipleemitTo()calls from the frontend- Multi-webview is unstable: requires
features = ["unstable"]in Cargo.toml and is desktop-only (no mobile support) - Window state plugin: does not restore maximized/fullscreen state by default -- use
StateFlags::all()to include all state dimensions - Platform differences: parent/child behavior varies -- macOS creates child windows, Linux uses transient windows, Windows creates owned windows
</red_flags>
<critical_reminders>
CRITICAL REMINDERS
(You MUST give every window a unique label -- labels identify windows for event targeting, permissions, and retrieval)
(You MUST always call the unlisten function returned by listen() / once() -- leaked listeners cause memory leaks in long-running apps)
(You MUST check if a window already exists before creating it -- duplicate labels cause runtime errors)
(You MUST add window labels to capability file windows array -- windows without permissions cannot use plugins or core APIs)
(You MUST use @tauri-apps/api/event for global events and @tauri-apps/api/webviewWindow for window-scoped events -- mixing them causes missed events)
Failure to follow these rules will cause runtime errors, memory leaks, silent permission failures, and missed events.
</critical_reminders>
Files (skills)
-
examples
-
advanced.md 7.8 KB
Loading… -
core.md 10 KB
Loading… -
persistence.md 4.3 KB
Loading…
-
-
reference.md 8.2 KB
Loading… -
SKILL.md 15.7 KB
--- name: desktop-multiwindow-tauri description: Tauri 2.x multi-window creation, event system, window state persistence, parent/child and modal windows --- # Tauri Multi-Window & Events > **Quick Guide:** Create windows from JS with `new WebviewWindow(label, options)` or from Rust with `WebviewWindowBuilder`. Communicate across windows using events: `emit()` broadcasts globally, `emitTo(label, event, payload)` targets a specific window, `emit_filter()` targets multiple windows by predicate. Always call the unlisten function returned by `listen()`. Use `tauri-plugin-window-state` to persist window position/size across sessions. Window labels must be unique and are used for both event targeting and permission scoping. > > **Current version:** Tauri 2.x (stable). Multi-webview in a single window requires the `unstable` feature flag. --- <critical_requirements> ## CRITICAL: Before Using This Skill **(You MUST give every window a unique label -- labels identify windows for event targeting, permissions, and retrieval)** **(You MUST always call the unlisten function returned by `listen()` / `once()` -- leaked listeners cause memory leaks in long-running apps)** **(You MUST check if a window already exists before creating it -- duplicate labels cause runtime errors)** **(You MUST add window labels to capability file `windows` array -- windows without permissions cannot use plugins or core APIs)** **(You MUST use `@tauri-apps/api/event` for global events and `@tauri-apps/api/webviewWindow` for window-scoped events -- mixing them causes missed events)** </critical_requirements> --- **Auto-detection:** WebviewWindow, WebviewWindowBuilder, emit_to, emitTo, emit_filter, EventTarget, window label, multi-window, onCloseRequested, tauri-plugin-window-state, parent window, modal window, WebviewBuilder, add_child, getCurrentWebviewWindow, window.listen, window.emit, cross-window communication **When to use:** - Creating secondary windows (settings, preferences, about, detached panels) - Communicating between windows via the Tauri event system - Handling window close confirmation (unsaved changes dialogs) - Persisting window size/position across app restarts - Setting up parent/child or modal window relationships - Building multi-panel layouts with multiple webviews in a single window **When NOT to use:** - Single-window apps with no inter-window communication (use the base Tauri framework skill) - General Tauri commands, IPC, or plugin setup (use the base Tauri framework skill) - Frontend framework state management within a single window (use respective framework skills) **Key patterns covered:** - Window creation from JS and Rust ([examples/core.md](examples/core.md)) - Event system: emit, emitTo, emit_filter for targeted messaging ([examples/core.md](examples/core.md)) - Cross-window state synchronization via events ([examples/core.md](examples/core.md)) - Window close confirmation with onCloseRequested ([examples/core.md](examples/core.md)) - Window state persistence with tauri-plugin-window-state ([examples/persistence.md](examples/persistence.md)) - Parent/child windows and modal dialogs ([examples/advanced.md](examples/advanced.md)) - Multi-webview in a single window (unstable) ([examples/advanced.md](examples/advanced.md)) **Detailed resources:** - [examples/core.md](examples/core.md) - Window creation, event system, close confirmation, cross-window sync - [examples/persistence.md](examples/persistence.md) - Window state plugin setup, manual save/restore, StateFlags - [examples/advanced.md](examples/advanced.md) - Parent/child windows, modals, multi-webview layouts - [reference.md](reference.md) - API quick reference, event method comparison, decision framework --- <philosophy> ## Philosophy Tauri's multi-window architecture is built on two key concepts: **window labels** for identification and **events** for communication. Every window has a unique string label assigned at creation. This label is used everywhere: event targeting with `emitTo`, permission scoping in capability files, and retrieval with `app.get_webview_window(label)`. Labels are the window's address. The event system follows a pub-sub model with three tiers of targeting: 1. **Global** (`emit`) -- all listeners in all windows receive the event 2. **Targeted** (`emitTo`) -- only listeners in the specified window receive the event 3. **Filtered** (`emit_filter`) -- listeners matching a predicate receive the event **When to use multi-window patterns:** - App needs separate UI surfaces (settings panel, file viewer, log output) - Need to decouple UI concerns into independent windows - Need modal dialogs that block interaction with the parent window - Need persistent panel layouts (IDE-style split views) **When NOT to use multi-window:** - A tabbed interface within a single window handles the use case - The secondary UI is a simple overlay/modal that lives in the same DOM - You only need to show/hide sections of a single-page app </philosophy> --- <patterns> ## Core Patterns ### Pattern 1: Window Creation Create windows from JavaScript or Rust. Always check if the window exists first to avoid duplicate-label errors. ```typescript import { WebviewWindow } from "@tauri-apps/api/webviewWindow"; const SETTINGS_WINDOW_LABEL = "settings"; const SETTINGS_WIDTH = 600; const SETTINGS_HEIGHT = 400; // Check if already open, focus it instead of creating duplicate const existing = await WebviewWindow.getByLabel(SETTINGS_WINDOW_LABEL); if (existing) { await existing.setFocus(); return; } const settingsWindow = new WebviewWindow(SETTINGS_WINDOW_LABEL, { url: "settings.html", title: "Settings", width: SETTINGS_WIDTH, height: SETTINGS_HEIGHT, resizable: false, center: true, }); settingsWindow.once("tauri://created", () => { console.log("Settings window created"); }); settingsWindow.once("tauri://error", (e) => { console.error("Failed to create window:", e); }); ``` **Why good:** checks for existing window first, uses named constants for dimensions, handles both creation success and error events See [examples/core.md](examples/core.md) for Rust-side creation with `WebviewWindowBuilder` and a full reusable helper. --- ### Pattern 2: Event System (Global, Targeted, Filtered) Three tiers of event emission -- choose the narrowest scope that fits. ```typescript import { emit, emitTo, listen } from "@tauri-apps/api/event"; // Global: all windows receive await emit("theme-changed", { theme: "dark" }); // Targeted: only the "editor" window receives await emitTo("editor", "file-opened", { path: "/docs/readme.md" }); ``` ```rust use tauri::{Emitter, EventTarget}; // Targeted: send to one window app.emit_to("editor", "file-opened", payload)?; // Filtered: send to multiple specific windows app.emit_filter("file-opened", payload, |target| match target { EventTarget::WebviewWindow { label } => label == "main" || label == "file-viewer", _ => false, })?; ``` **Key decision:** Use `emit()` for app-wide broadcasts (theme changes, user logout). Use `emitTo()` when you know the exact target window. Use `emit_filter()` when targeting multiple specific windows. See [examples/core.md](examples/core.md) for the full listening pattern with cleanup and cross-window state sync. --- ### Pattern 3: Window Close Confirmation Intercept the close request to show a confirmation dialog (e.g., unsaved changes). ```typescript import { getCurrentWindow } from "@tauri-apps/api/window"; const unlisten = await getCurrentWindow().onCloseRequested(async (event) => { if (hasUnsavedChanges()) { event.preventDefault(); // Show your confirmation UI, then call window.close() or window.destroy() if confirmed } }); // Clean up listener when no longer needed unlisten(); ``` **Key point:** `event.preventDefault()` stops the window from closing. You must then either close it programmatically when the user confirms or leave it open. `destroy()` force-closes without triggering close-requested again. See [examples/core.md](examples/core.md) for the Rust-side equivalent using `on_window_event`. --- ### Pattern 4: Window State Persistence Use `tauri-plugin-window-state` to automatically save and restore window position/size across sessions. ```rust tauri::Builder::default() .setup(|app| { #[cfg(desktop)] app.handle().plugin( tauri_plugin_window_state::Builder::default().build() ); Ok(()) }) ``` **Key point:** Set `visible: false` in window config and let the plugin show the window after restoring state -- prevents a flash of the default position before restore. See [examples/persistence.md](examples/persistence.md) for manual save/restore and StateFlags. --- ### Pattern 5: Parent/Child and Modal Windows Create owned windows that are tied to a parent. Modal windows block interaction with the parent until closed. ```typescript import { WebviewWindow, getCurrentWebviewWindow, } from "@tauri-apps/api/webviewWindow"; const DIALOG_LABEL = "confirm-dialog"; const DIALOG_WIDTH = 400; const DIALOG_HEIGHT = 200; const parent = getCurrentWebviewWindow(); const dialog = new WebviewWindow(DIALOG_LABEL, { url: "confirm.html", title: "Confirm Action", width: DIALOG_WIDTH, height: DIALOG_HEIGHT, parent: parent, center: true, }); ``` ```rust use tauri::WebviewWindowBuilder; const DIALOG_WIDTH: f64 = 400.0; const DIALOG_HEIGHT: f64 = 200.0; WebviewWindowBuilder::new(&app, "confirm-dialog", tauri::WebviewUrl::App("confirm.html".into())) .title("Confirm Action") .inner_size(DIALOG_WIDTH, DIALOG_HEIGHT) .parent(&parent_window)? .center() .build()?; ``` **Key point:** On macOS, parent makes the child a child window. On Linux, it makes it transient. Owned windows are hidden when the parent is minimized. See [examples/advanced.md](examples/advanced.md) for modal patterns. --- ### Pattern 6: Multi-Webview in a Single Window (Unstable) Create multiple webviews within a single window for panel/splitter layouts. Requires the `unstable` Cargo feature. ```rust // Cargo.toml: tauri = { version = "2", features = ["unstable"] } use tauri::{LogicalPosition, LogicalSize}; use tauri::webview::WebviewBuilder; use tauri::window::WindowBuilder; let window = WindowBuilder::new(&app, "main") .inner_size(1200.0, 800.0) .build()?; let sidebar_width = 300.0; let main_width = 900.0; let height = 800.0; window.add_child( WebviewBuilder::new("sidebar", tauri::WebviewUrl::App("sidebar.html".into())), LogicalPosition::new(0.0, 0.0), LogicalSize::new(sidebar_width, height), )?; window.add_child( WebviewBuilder::new("content", tauri::WebviewUrl::App("content.html".into())), LogicalPosition::new(sidebar_width, 0.0), LogicalSize::new(main_width, height), )?; ``` **Key point:** This is behind the `unstable` feature flag and is desktop-only. Each child webview gets its own label and can communicate via the event system. See [examples/advanced.md](examples/advanced.md) for resizing patterns. </patterns> --- <decision_framework> ## Decision Framework ### Event Targeting ``` Who should receive this event? |-- ALL windows in the app? | +-- emit() (global broadcast) |-- ONE specific window? | +-- emitTo(label, event, payload) (targeted) |-- MULTIPLE specific windows (but not all)? | +-- emit_filter() with predicate (Rust only) +-- The backend (Rust side)? +-- emit() from frontend + app.listen() in Rust ``` ### Window Architecture ``` Does this UI surface need to be a separate window? |-- Is it a settings/preferences panel? | +-- YES: separate window with its own label |-- Is it a modal confirmation dialog? | +-- YES: child window with parent set |-- Is it a dockable/undockable panel (IDE-style)? | +-- YES: multi-webview in single window (unstable) |-- Is it content that can live in the same DOM? | +-- NO: don't create a new window -- use in-app routing/tabs +-- Does it need to persist across window close? +-- YES: use tauri-plugin-window-state ``` ### Where to Create Windows ``` Where does window creation belong? |-- Triggered by user action in UI (button click)? | +-- Frontend: new WebviewWindow(label, options) |-- Triggered by backend logic (file watcher, system event)? | +-- Rust: WebviewWindowBuilder::new(app, label, url) |-- Need multiple webviews in one window? | +-- Rust: WindowBuilder + window.add_child(WebviewBuilder) +-- Declared at startup in config? +-- tauri.conf.json "windows" array ``` See [reference.md](reference.md) for the complete API quick reference. </decision_framework> --- <red_flags> ## RED FLAGS **High Priority Issues:** - Duplicate window labels -- creating a window with a label that already exists throws a runtime error; always check first with `getByLabel()` or `app.get_webview_window()` - Missing unlisten calls -- `listen()` returns an unlisten function; not calling it leaks memory, especially in long-running apps or components that mount/unmount - Window label not in capability file `windows` array -- the new window silently lacks permissions for plugins and core APIs - Using `@tauri-apps/api/tauri` for event imports -- removed in v2; use `@tauri-apps/api/event` for global events and `@tauri-apps/api/webviewWindow` for window-scoped events - Calling `emit()` when you mean `emitTo()` -- broadcasting sensitive events (auth tokens, user data) to all windows is a security risk **Medium Priority Issues:** - Not handling `tauri://error` event on window creation -- creation can fail silently without this listener - Using `close()` after `preventDefault()` in close handler -- triggers the close-requested event again; use `destroy()` to force-close without re-triggering - Hardcoding window dimensions without named constants -- magic numbers make layouts harder to maintain - Not using `center: true` or explicit position -- windows appear at OS-default position, which may be off-screen on multi-monitor setups **Gotchas & Edge Cases:** - **`onCloseRequested` on dynamic windows:** there is a known issue where `event.preventDefault()` may not work on windows created at runtime; use the Rust `on_window_event` approach as a fallback - **Event payload serialization:** payloads must be serializable (JSON-compatible from JS, `serde::Serialize` from Rust); complex types like functions or DOM nodes cannot be sent - **Window labels:** must be alphanumeric with `-`, `/`, `:`, `_` characters only -- no spaces or special characters - **Multi-monitor:** `center()` centers on the primary monitor; for specific monitor positioning use `setPosition()` with `PhysicalPosition` - **`emit_filter` is Rust-only:** there is no JavaScript equivalent; use multiple `emitTo()` calls from the frontend - **Multi-webview is unstable:** requires `features = ["unstable"]` in Cargo.toml and is desktop-only (no mobile support) - **Window state plugin:** does not restore maximized/fullscreen state by default -- use `StateFlags::all()` to include all state dimensions - **Platform differences:** parent/child behavior varies -- macOS creates child windows, Linux uses transient windows, Windows creates owned windows </red_flags> --- <critical_reminders> ## CRITICAL REMINDERS **(You MUST give every window a unique label -- labels identify windows for event targeting, permissions, and retrieval)** **(You MUST always call the unlisten function returned by `listen()` / `once()` -- leaked listeners cause memory leaks in long-running apps)** **(You MUST check if a window already exists before creating it -- duplicate labels cause runtime errors)** **(You MUST add window labels to capability file `windows` array -- windows without permissions cannot use plugins or core APIs)** **(You MUST use `@tauri-apps/api/event` for global events and `@tauri-apps/api/webviewWindow` for window-scoped events -- mixing them causes missed events)** **Failure to follow these rules will cause runtime errors, memory leaks, silent permission failures, and missed events.** </critical_reminders>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.