webview

Provides APIs to create webviews, communicate with other webviews and manipulate the current webview.

Webview events

Events can be listened to using Webview.listen:

import { getCurrent } from '@tauri-apps/api/webview';
getCurrent().listen('my-webview-event', ({ event, payload }) => {});

Classes

Webview

Create new webview or get a handle to an existing one.

Webviews are identified by a label a unique identifier that can be used to reference it later. It may only contain alphanumeric characters a-zA-Z plus the following special characters -, /, : and _.

Example

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

const appWindow = new Window('uniqueLabel');

// loading embedded asset:
const webview = new Webview(appWindow, 'theUniqueLabel', {
  url: 'path/to/page.html',
});
// alternatively, load a remote URL:
const webview = new Webview(appWindow, 'theUniqueLabel', {
  url: 'https://github.com/tauri-apps/tauri',
});

webview.once('tauri://created', function () {
  // webview successfully created
});
webview.once('tauri://error', function (e) {
  // an error happened creating the webview
});

// emit an event to the backend
await webview.emit('some-event', 'data');
// listen to an event from the backend
const unlisten = await webview.listen('event-name', (e) => {});
unlisten();

Since

2.0.0

Extended By

WebviewWindow

Constructors

constructor()

new Webview(
  window,
  label,
  options): Webview

Creates a new Webview.

Example

import { Window } from '@tauri-apps/api/window';
import { Webview } from '@tauri-apps/api/webview';
const appWindow = new Window('my-label');
const webview = new Webview(appWindow, 'my-label', {
  url: 'https://github.com/tauri-apps/tauri',
});
webview.once('tauri://created', function () {
  // webview successfully created
});
webview.once('tauri://error', function (e) {
  // an error happened creating the webview
});

Parameters

Parameter	Type	Description
`window`	`Window`	the window to add this webview to.
`label`	`string`	The unique webview label. Must be alphanumeric: `a-zA-Z-/:_`.
`options`	`WebviewOptions`	-

Returns

Webview

The Webview instance to communicate with the webview.

Source: webview.ts:159

Properties

Property	Type	Description
`label`	`string`	The webview label. It is a unique identifier for the webview, can be used to reference it later.
`listeners`	`Record`< `string`, `EventCallback`< `any` >[] >	Local event listeners.
`window`	`Window`	The window hosting this webview.

Methods

close()

close(): Promise< void >

Closes the webview.

Example

import { getCurrent } from '@tauri-apps/api/webview';
await getCurrent().close();

Returns

Promise< void >

A promise indicating the success or failure of the operation.

Source: webview.ts:396

emit()

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

Emits an event to all targets.

Example

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

Parameters

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

Returns

Promise< void >

Source: webview.ts:285

emitTo()

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

Emits an event to all targets matching the given target.

Example

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

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`?	`unknown`	Event payload.

Returns

Promise< void >

Source: webview.ts:313

listen()

listen<T>(event, handler): Promise< UnlistenFn >

Listen to an emitted event on this webview.

Example

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

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Type parameters

Parameter
`T`

Parameters

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

Returns

Promise< UnlistenFn >

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Source: webview.ts:225

onDragDropEvent()

onDragDropEvent(handler): Promise< UnlistenFn >

Listen to a file drop event. The listener is triggered when the user hovers the selected files on the webview, drops the files or cancels the operation.

Example

import { getCurrent } from '@tauri-apps/api/webview';
const unlisten = await getCurrent().onDragDropEvent((event) => {
  if (event.payload.type === 'hover') {
    console.log('User hovering', event.payload.paths);
  } else if (event.payload.type === 'drop') {
    console.log('User dropped', event.payload.paths);
  } else {
    console.log('File drop cancelled');
  }
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Parameter	Type
`handler`	`EventCallback`< `DragDropEvent` >

Returns

Promise< UnlistenFn >

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Source: webview.ts:544

once()

once<T>(event, handler): Promise< UnlistenFn >

Listen to an emitted event on this webview only once.

Example

import { getCurrent } from '@tauri-apps/api/webview';
const unlisten = await getCurrent().once<null>('initialized', (event) => {
  console.log(`Webview initialized!`);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Type parameters

Parameter
`T`

Parameters

Parameter	Type	Description
`event`	`string`	Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`.
`handler`	`EventCallback`< `T` >	Event handler.

Returns

Promise< UnlistenFn >

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Source: webview.ts:260

position()

position(): Promise< PhysicalPosition >

The position of the top-left hand corner of the webview’s client area relative to the top-left hand corner of the desktop.

Example

import { getCurrent } from '@tauri-apps/api/webview';
const position = await getCurrent().position();

Returns

Promise< PhysicalPosition >

The webview’s position.

Source: webview.ts:358

reparent()

reparent(window): Promise< void >

Moves this webview to the given label.

Example

import { getCurrent } from '@tauri-apps/api/webview';
await getCurrent().reparent('other-window');

Parameters

Parameter	Type
`window`	`string` \| `Window` \| `WebviewWindow`

Returns

Promise< void >

A promise indicating the success or failure of the operation.

Source: webview.ts:510

setFocus()

setFocus(): Promise< void >

Bring the webview to front and focus.

Example

import { getCurrent } from '@tauri-apps/api/webview';
await getCurrent().setFocus();

Returns

Promise< void >

A promise indicating the success or failure of the operation.

Source: webview.ts:477

setPosition()

setPosition(position): Promise< void >

Sets the webview position.

Example

import { getCurrent, LogicalPosition } from '@tauri-apps/api/webview';
await getCurrent().setPosition(new LogicalPosition(600, 500));

Parameters

Parameter	Type	Description
`position`	`LogicalPosition` \| `PhysicalPosition`	The new position, in logical or physical pixels.

Returns

Promise< void >

A promise indicating the success or failure of the operation.

Source: webview.ts:443

setSize()

setSize(size): Promise< void >

Resizes the webview.

Example

import { getCurrent, LogicalSize } from '@tauri-apps/api/webview';
await getCurrent().setSize(new LogicalSize(600, 500));

Parameters

Parameter	Type	Description
`size`	`LogicalSize` \| `PhysicalSize`	The logical or physical size.

Returns

Promise< void >

A promise indicating the success or failure of the operation.

Source: webview.ts:413

setZoom()

setZoom(scaleFactor): Promise< void >

Set webview zoom level.

Example

import { getCurrent } from '@tauri-apps/api/webview';
await getCurrent().setZoom(1.5);

Parameters

Parameter	Type
`scaleFactor`	`number`

Returns

Promise< void >

A promise indicating the success or failure of the operation.

Source: webview.ts:493

size()

size(): Promise< PhysicalSize >

The physical size of the webview’s client area. The client area is the content of the webview, excluding the title bar and borders.

Example

import { getCurrent } from '@tauri-apps/api/webview';
const size = await getCurrent().size();

Returns

Promise< PhysicalSize >

The webview’s size.

Source: webview.ts:375

getAll()

static getAll(): Webview[]

Gets a list of instances of Webview for all available webviews.

Returns

Webview[]

Source: webview.ts:202

getByLabel()

static getByLabel(label): null | Webview

Gets the Webview for the webview associated with the given label.

Example

import { Webview } from '@tauri-apps/api/webview';
const mainWebview = Webview.getByLabel('main');

Parameters

Parameter	Type	Description
`label`	`string`	The webview label.

Returns

null | Webview

The Webview instance to communicate with the webview or null if the webview doesn’t exist.

Source: webview.ts:188

getCurrent()

static getCurrent(): Webview

Get an instance of Webview for the current webview.

Property	Type	Description
`acceptFirstMouse`?	`boolean`	Whether clicking an inactive webview also clicks through to the webview on macOS.
`dragDropEnabled`?	`boolean`	Whether the drag and drop is enabled or not on the webview. By default it is enabled. Disabling it is required to use HTML5 drag and drop on the frontend on Windows.
`height`	`number`	The initial height.
`incognito`?	`boolean`	Whether or not the webview should be launched in incognito mode. #### Platform-specific - Android: Unsupported.
`proxyUrl`?	`string`	The proxy URL for the WebView for all network requests. Must be either a `http://` or a `socks5://` URL. #### Platform-specific - macOS: Requires the `macos-proxy` feature flag and only compiles for macOS 14+.
`transparent`?	`boolean`	Whether the webview is transparent or not. Note that on `macOS` this requires the `macos-private-api` feature flag, enabled under `tauri.conf.json > app > macOSPrivateApi`. WARNING: Using private APIs on `macOS` prevents your application from being accepted to the `App Store`.
`url`?	`string`	Remote URL or local file path to open. - URL such as `https://github.com/tauri-apps` is opened directly on a Tauri webview. - data: URL such as `data:text/html,<html>...` is only supported with the `webview-data-url` Cargo feature for the `tauri` dependency. - local file path or route such as `/path/to/page.html` or `/users` is appended to the application URL (the devServer URL on development, or `tauri://localhost/` and `https://tauri.localhost/` on production).
`userAgent`?	`string`	The user agent for the webview.
`width`	`number`	The initial width.
`x`	`number`	The initial vertical position.
`y`	`number`	The initial horizontal position.
`zoomHotkeysEnabled`?	`boolean`	Whether page zooming by hotkeys is enabled ## Platform-specific: - Windows: Controls WebView2’s `IsZoomControlEnabled` setting. - MacOS / Linux: Injects a polyfill that zooms in and out with `ctrl/command` + `-/=`, 20% in each step, ranging from 20% to 1000%. Requires `webview:allow-set-webview-zoom` permission - Android / iOS: Unsupported.

Functions

getAll()

getAll(): Webview[]

Gets a list of instances of Webview for all available webviews.

getCurrent(): Webview

Get an instance of Webview for the current webview.

Since

2.0.0

Returns

Webview

Source: webview.ts:57