OpenAEC-Foundation/tauri-syntax-webview

tauri-syntax-webview

Quick Reference

Webview API Imports

| Import | Purpose | Example | |--------|---------|---------| | getCurrentWebview() | Get the current webview instance | const wv = getCurrentWebview() | | getAllWebviews() | Get all webview instances | const all = await getAllWebviews() | | Webview | Webview class for creation and reference | new Webview(window, 'label', opts) |

Import path: import { Webview, getCurrentWebview, getAllWebviews } from '@tauri-apps/api/webview'

Webview Methods (TypeScript)

| Method | Returns | Description | |--------|---------|-------------| | setZoom(factor) | Promise<void> | Set webview zoom level (1.0 = 100%) | | clearAllBrowsingData() | Promise<void> | Clear all browsing data | | size() | Promise<PhysicalSize> | Get webview size | | position() | Promise<PhysicalPosition> | Get webview position | | setSize(size) | Promise<void> | Set webview size | | setPosition(pos) | Promise<void> | Set webview position | | setAutoResize(enabled) | Promise<void> | Auto-resize with parent window | | show() | Promise<void> | Show the webview | | hide() | Promise<void> | Hide the webview | | setFocus() | Promise<void> | Focus the webview | | reparent(windowLabel) | Promise<void> | Move webview to another window | | close() | Promise<void> | Close and destroy the webview | | listen(event, handler) | Promise<UnlistenFn> | Listen for events on this webview | | onDragDropEvent(handler) | Promise<UnlistenFn> | Listen for drag-drop events |

Webview vs Window vs WebviewWindow

| Concept | Description | Use When | |---------|-------------|----------| | Window | Native OS window container (title bar, frame) | Managing window chrome, position, visibility | | Webview | Web content renderer inside a window | Multiple web panels in one window | | WebviewWindow | Combined window + single webview (convenience) | Standard single-webview-per-window apps |

Critical Warnings

NEVER create a Webview without specifying a parent Window -- webviews MUST live inside a window.

NEVER assume getCurrentWebview() and getCurrentWindow() return the same object -- a window can contain multiple webviews.

ALWAYS use LogicalSize / LogicalPosition from @tauri-apps/api/dpi for sizing and positioning to handle DPI scaling correctly.

ALWAYS call setAutoResize(true) when a webview should fill its parent window, otherwise the webview will NOT resize when the window resizes.

NEVER forget that reparent() takes a window label string, not a Window object.

---

Essential Patterns

Pattern 1: Getting the Current Webview

import { getCurrentWebview } from '@tauri-apps/api/webview';

const webview = getCurrentWebview();
console.log('Webview label:', webview.label);

Every webview has a unique label string identifier. The label is set at creation time and cannot be changed.

Pattern 2: Creating a Webview Inside an Existing Window

import { Webview } from '@tauri-apps/api/webview';
import { getCurrentWindow } from '@tauri-apps/api/window';

const parentWindow = getCurrentWindow();

const sidePanel = new Webview(parentWindow, 'side-panel', {
  url: 'https://example.com',
  x: 0,
  y: 0,
  width: 400,
  height: 300,
});

The constructor parameters are: parent window, unique label, and options with url, x, y, width, height.

Pattern 3: Multi-Webview Layout

import { Webview } from '@tauri-apps/api/webview';
import { getCurrentWindow } from '@tauri-apps/api/window';
import { LogicalSize, LogicalPosition } from '@tauri-apps/api/dpi';

const win = getCurrentWindow();

// Create a sidebar webview
const sidebar = new Webview(win, 'sidebar', {
  url: '/sidebar.html',
  x: 0,
  y: 0,
  width: 250,
  height: 600,
});

// Create a main content webview
const content = new Webview(win, 'content', {
  url: '/main.html',
  x: 250,
  y: 0,
  width: 550,
  height: 600,
});

Pattern 4: Webview Sizing and Positioning

import { getCurrentWebview } from '@tauri-apps/api/webview';
import { LogicalSize, LogicalPosition } from '@tauri-apps/api/dpi';

const webview = getCurrentWebview();

// Get current dimensions
const size = await webview.size();
const pos = await webview.position();

// Resize
await webview.setSize(new LogicalSize(400, 300));

// Reposition
await webview.setPosition(new LogicalPosition(100, 50));

// Auto-resize to fill parent window
await webview.setAutoResize(true);

Pattern 5: Reparenting a Webview

import { getCurrentWebview } from '@tauri-apps/api/webview';

const webview = getCurrentWebview();

// Move this webview to a different window by label
await webview.reparent('other-window');

Reparenting moves the webview from its current parent window to the window identified by the given label string.

Pattern 6: Zoom Control

import { getCurrentWebview } from '@tauri-apps/api/webview';

const webview = getCurrentWebview();

// Set zoom to 150%
await webview.setZoom(1.5);

// Reset to default
await webview.setZoom(1.0);

Pattern 7: Webview Events

import { getCurrentWebview } from '@tauri-apps/api/webview';

const webview = getCurrentWebview();

// Listen for custom events scoped to this webview
const unlisten = await webview.listen<string>('content-loaded', (event) => {
  console.log('Content loaded:', event.payload);
});

// Drag-drop events
const unlistenDrop = await webview.onDragDropEvent((event) => {
  if (event.payload.type === 'drop') {
    console.log('Files dropped:', event.payload.paths);
  }
});

// Clean up
unlisten();
unlistenDrop();

Pattern 8: Webview Events in React

import { useEffect } from 'react';
import { getCurrentWebview } from '@tauri-apps/api/webview';

function MyComponent() {
  useEffect(() => {
    const webview = getCurrentWebview();
    const promise = webview.onDragDropEvent((event) => {
      if (event.payload.type === 'drop') {
        console.log('Dropped:', event.payload.paths);
      }
    });

    return () => {
      promise.then((unlisten) => unlisten());
    };
  }, []);

  return <div>Drop files here</div>;
}

ALWAYS clean up webview event listeners in the component teardown to prevent memory leaks.

---

Rust Side: WebviewBuilder

For creating webviews from Rust, use WebviewBuilder:

use tauri::webview::WebviewBuilder;
use tauri::WebviewUrl;

// Inside setup() or any context with Manager access
let webview = WebviewBuilder::new(
    "side-panel",
    WebviewUrl::App("panel.html".into()),
)
.auto_resize()
.build()?;

// Attach to a window
window.add_child(
    webview,
    tauri::LogicalPosition::new(0.0, 0.0),
    tauri::LogicalSize::new(400.0, 600.0),
)?;

Rust WebviewWindowBuilder (Combined Window + Webview)

For the common case of one webview per window:

use tauri::webview::WebviewWindowBuilder;
use tauri::WebviewUrl;

let webview_window = WebviewWindowBuilder::new(
    app,
    "editor",
    WebviewUrl::App("editor.html".into()),
)
.title("Editor")
.inner_size(800.0, 600.0)
.build()?;

---

Drag-Drop Event Types

| Event Type | Fields | Description | |------------|--------|-------------| | enter | paths: string[], position: PhysicalPosition | Files entered the webview area | | over | position: PhysicalPosition | Files hovering over the webview | | drop | paths: string[], position: PhysicalPosition | Files dropped on the webview | | leave | -- | Files left the webview area |

Built-in TauriEvent constants for drag-drop:

| Constant | Value | |----------|-------| | TauriEvent.DRAG_ENTER | "tauri://drag-enter" | | TauriEvent.DRAG_OVER | "tauri://drag-over" | | TauriEvent.DRAG_DROP | "tauri://drag-drop" | | TauriEvent.DRAG_LEAVE | "tauri://drag-leave" |

---

Permissions

Webview operations require core permissions in your capability file:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "webview-capability",
  "windows": ["main"],
  "permissions": [
    "core:webview:default",
    "core:webview:allow-create-webview",
    "core:webview:allow-set-webview-size",
    "core:webview:allow-set-webview-position",
    "core:webview:allow-set-webview-zoom",
    "core:webview:allow-reparent",
    "core:webview:allow-webview-close"
  ]
}

ALWAYS add webview permissions to your capability file. Without them, all webview API calls throw "command not allowed" errors at runtime.

---

Reference Links

• references/methods.md -- Complete API signatures for Webview class, WebviewBuilder, and related types
• references/examples.md -- Working code examples for multi-webview layouts, drag-drop, and reparenting
• references/anti-patterns.md -- What NOT to do with webviews, with explanations

Official Sources

• https://v2.tauri.app/reference/javascript/api/namespacewebview/
• https://v2.tauri.app/reference/javascript/api/namespacedpi/
• https://docs.rs/tauri/latest/tauri/webview/index.html