Skip to content
Tauri

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 { getCurrentWebview } from "@tauri-apps/api/webview";
getCurrentWebview().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

Constructors

new Webview()
new Webview(
window,
label,
options): Webview

Creates a new Webview.

Parameters
ParameterTypeDescription
windowWindowthe window to add this webview to.
labelstringThe unique webview label. Must be alphanumeric: a-zA-Z-/:_.
optionsWebviewOptions-
Returns

Webview

The Webview instance to communicate with the 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
});

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

Properties

PropertyTypeDescriptionDefined in
labelstringThe webview label. It is a unique identifier for the webview, can be used to reference it later.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L130
listenersRecord<string, EventCallback<any>[]>Local event listeners.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L135
windowWindowThe window hosting this webview.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L132

Methods

clearAllBrowsingData()
clearAllBrowsingData(): Promise<void>

Clears all browsing data for this webview.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Example
import { getCurrentWebview } from '@tauri-apps/api/webview';
await getCurrentWebview().clearAllBrowsingData();

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

close()
close(): Promise<void>

Closes the webview.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

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

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

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

Emits an event to all targets.

Parameters
ParameterTypeDescription
eventstringEvent name. Must include only alphanumeric characters, -, /, : and _.
payload?unknownEvent payload.
Returns

Promise<void>

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

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

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

Emits an event to all targets matching the given target.

Parameters
ParameterTypeDescription
targetstring | EventTargetLabel of the target Window/Webview/WebviewWindow or raw EventTarget object.
eventstringEvent name. Must include only alphanumeric characters, -, /, : and _.
payload?unknownEvent payload.
Returns

Promise<void>

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

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

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

Listen to an emitted event on this webview.

Type Parameters
Type Parameter
T
Parameters
ParameterTypeDescription
eventEventNameEvent name. Must include only alphanumeric characters, -, /, : and _.
handlerEventCallback<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.

Example
import { getCurrentWebview } from '@tauri-apps/api/webview';
const unlisten = await getCurrentWebview().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();

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

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

Listen to an emitted event on this webview only once.

Type Parameters
Type Parameter
T
Parameters
ParameterTypeDescription
eventEventNameEvent name. Must include only alphanumeric characters, -, /, : and _.
handlerEventCallback<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.

Example
import { getCurrentWebview } 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();

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

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.

Parameters
ParameterType
handlerEventCallback<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.

Example
import { getCurrentWebview } from "@tauri-apps/api/webview";
const unlisten = await getCurrentWebview().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();

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

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.

Returns

Promise<PhysicalPosition>

The webview’s position.

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

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

reparent()
reparent(window): Promise<void>

Moves this webview to the given label.

Parameters
ParameterType
windowstring | Window | WebviewWindow
Returns

Promise<void>

A promise indicating the success or failure of the operation.

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

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

setFocus()
setFocus(): Promise<void>

Bring the webview to front and focus.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

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

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

setPosition()
setPosition(position): Promise<void>

Sets the webview position.

Parameters
ParameterTypeDescription
positionLogicalPosition | PhysicalPositionThe new position, in logical or physical pixels.
Returns

Promise<void>

A promise indicating the success or failure of the operation.

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

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

setSize()
setSize(size): Promise<void>

Resizes the webview.

Parameters
ParameterTypeDescription
sizeLogicalSize | PhysicalSizeThe logical or physical size.
Returns

Promise<void>

A promise indicating the success or failure of the operation.

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

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

setZoom()
setZoom(scaleFactor): Promise<void>

Set webview zoom level.

Parameters
ParameterType
scaleFactornumber
Returns

Promise<void>

A promise indicating the success or failure of the operation.

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

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

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.

Returns

Promise<PhysicalSize>

The webview’s size.

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

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

getAll()
static getAll(): Promise<Webview[]>

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

Returns

Promise<Webview[]>

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

getByLabel()
static getByLabel(label): Promise<null | Webview>

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

Parameters
ParameterTypeDescription
labelstringThe webview label.
Returns

Promise<null | Webview>

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

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

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

getCurrent()
static getCurrent(): Webview

Get an instance of Webview for the current webview.

Returns

Webview

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

Interfaces

WebviewOptions

Configuration for the webview to create.

Since

2.0.0

Properties

PropertyTypeDescriptionDefined in
acceptFirstMouse?booleanWhether clicking an inactive webview also clicks through to the webview on macOS.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L664
dragDropEnabled?booleanWhether 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.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L660
heightnumberThe initial height.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L648
incognito?booleanWhether or not the webview should be launched in incognito mode. #### Platform-specific - Android: Unsupported.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L676
proxyUrl?stringThe 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+.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L686
transparent?booleanWhether 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.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L654
url?stringRemote 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).Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L640
userAgent?stringThe user agent for the webview.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L668
widthnumberThe initial width.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L646
xnumberThe initial vertical position.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L642
ynumberThe initial horizontal position.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L644
zoomHotkeysEnabled?booleanWhether 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.Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L698

Type Aliases

DragDropEvent

type DragDropEvent: object | object | object | object;

The drag and drop event types.

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

Functions

getAllWebviews()

function getAllWebviews(): Promise<Webview[]>

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

Returns

Promise<Webview[]>

Since

2.0.0

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


getCurrentWebview()

function getCurrentWebview(): Webview

Get an instance of Webview for the current webview.

Returns

Webview

Since

2.0.0

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


© 2024 Tauri Contributors. CC-BY / MIT