webview
Ce contenu n’est pas encore disponible dans votre langue.
Provides APIs to create webviews, communicate with other webviews and manipulate the current webview.
Events can be listened to using Webview.listen:
import { getCurrentWebview } from "@tauri-apps/api/webview";getCurrentWebview().listen("my-webview-event", ({ event, payload }) => { });
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 _
.
import { Window } from "@tauri-apps/api/window"import { Webview } from "@tauri-apps/api/webview"
const appWindow = new Window('uniqueLabel');
appWindow.once('tauri://created', async function () { // `new Webview` Should be called after the window is successfully created, // or webview may not be attached to the window since window is not created yet.
// loading embedded asset: const webview = new Webview(appWindow, 'theUniqueLabel', { url: 'path/to/page.html',
// create a webview with specific logical position and size x: 0, y: 0, width: 800, height: 600, }); // alternatively, load a remote URL: const webview = new Webview(appWindow, 'theUniqueLabel', { url: 'https://github.com/tauri-apps/tauri',
// create a webview with specific logical position and size x: 0, y: 0, width: 800, height: 600, });
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();});
2.0.0
new Webview( window, label, options): Webview
Creates a new Webview.
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 | - |
The Webview instance to communicate with the webview.
import { Window } from '@tauri-apps/api/window'import { Webview } from '@tauri-apps/api/webview'const appWindow = new Window('my-label')
appWindow.once('tauri://created', async function() { const webview = new Webview(appWindow, 'my-label', { url: 'https://github.com/tauri-apps/tauri',
// create a webview with specific logical position and size x: 0, y: 0, width: 800, height: 600, });
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#L193
Property | Type | Description | Defined in |
---|---|---|---|
label | string | The 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#L154 |
listeners | Record <string , EventCallback <any >[]> | Local event listeners. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L159 |
window | Window | The window hosting this webview. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L156 |
clearAllBrowsingData(): Promise<void>
Clears all browsing data for this webview.
Promise
<void
>
A promise indicating the success or failure of the operation.
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().clearAllBrowsingData();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L588
close(): Promise<void>
Closes the webview.
Promise
<void
>
A promise indicating the success or failure of the operation.
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().close();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L435
emit<T>(event, payload?): Promise<void>
Emits an event to all targets.
Type Parameter |
---|
T |
Parameter | Type | Description |
---|---|---|
event | string | Event name. Must include only alphanumeric characters, - , / , : and _ . |
payload ? | T | Event payload. |
Promise
<void
>
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#L324
emitTo<T>( target, event,payload?): Promise<void>
Emits an event to all targets matching the given target.
Type Parameter |
---|
T |
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 ? | T | Event payload. |
Promise
<void
>
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#L352
hide(): Promise<void>
Hide the webview.
Promise
<void
>
A promise indicating the success or failure of the operation.
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().hide();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L522
listen<T>(event, handler): Promise<UnlistenFn>
Listen to an emitted event on this webview.
Type Parameter |
---|
T |
Parameter | Type | Description |
---|---|---|
event | EventName | Event name. Must include only alphanumeric characters, - , / , : and _ . |
handler | EventCallback <T > | Event handler. |
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.
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 unmountedunlisten();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L261
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.
Parameter | Type |
---|---|
handler | EventCallback <DragDropEvent > |
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.
import { getCurrentWebview } from "@tauri-apps/api/webview";const unlisten = await getCurrentWebview().onDragDropEvent((event) => { if (event.payload.type === 'over') { console.log('User hovering', event.payload.position); } 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 unmountedunlisten();
When the debugger panel is open, the drop position of this event may be inaccurate due to a known limitation. To retrieve the correct drop position, please detach the debugger.
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L640
once<T>(event, handler): Promise<UnlistenFn>
Listen to an emitted event on this webview only once.
Type Parameter |
---|
T |
Parameter | Type | Description |
---|---|---|
event | EventName | Event name. Must include only alphanumeric characters, - , / , : and _ . |
handler | EventCallback <T > | Event handler. |
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.
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 unmountedunlisten();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L296
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.
The webview’s position.
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#L397
reparent(window): Promise<void>
Moves this webview to the given label.
Parameter | Type |
---|---|
window | string | Window | WebviewWindow |
Promise
<void
>
A promise indicating the success or failure of the operation.
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#L571
setAutoResize(autoResize): Promise<void>
Sets whether the webview should automatically grow and shrink its size and position when the parent window resizes.
Parameter | Type |
---|---|
autoResize | boolean |
Promise
<void
>
A promise indicating the success or failure of the operation.
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().setAutoResize(true);
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L505
setBackgroundColor(color): Promise<void>
Specify the webview background color.
- macOS / iOS: Not implemented.
- Windows:
- On Windows 7, transparency is not supported and the alpha value will be ignored.
- On Windows higher than 7: translucent colors are not supported so any alpha value other than
0
will be replaced by255
Parameter | Type |
---|---|
color | null | Color |
Promise
<void
>
A promise indicating the success or failure of the operation.
2.1.0
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L606
setFocus(): Promise<void>
Bring the webview to front and focus.
Promise
<void
>
A promise indicating the success or failure of the operation.
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().setFocus();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L489
setPosition(position): Promise<void>
Sets the webview position.
Parameter | Type | Description |
---|---|---|
position | LogicalPosition | PhysicalPosition | Position | The new position, in logical or physical pixels. |
Promise
<void
>
A promise indicating the success or failure of the operation.
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#L470
setSize(size): Promise<void>
Resizes the webview.
Parameter | Type | Description |
---|---|---|
size | LogicalSize | PhysicalSize | Size | The logical or physical size. |
Promise
<void
>
A promise indicating the success or failure of the operation.
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#L452
setZoom(scaleFactor): Promise<void>
Set webview zoom level.
Parameter | Type |
---|---|
scaleFactor | number |
Promise
<void
>
A promise indicating the success or failure of the operation.
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#L554
show(): Promise<void>
Show the webview.
Promise
<void
>
A promise indicating the success or failure of the operation.
import { getCurrentWebview } from '@tauri-apps/api/webview';await getCurrentWebview().show();
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L538
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.
The webview’s size.
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#L414
static getAll(): Promise<Webview[]>
Gets a list of instances of Webview
for all available webviews.
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L238
static getByLabel(label): Promise<null | Webview>
Gets the Webview for the webview associated with the given label.
Parameter | Type | Description |
---|---|---|
label | string | The webview label. |
The Webview instance to communicate with the webview or null if the webview doesn’t exist.
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#L224
static getCurrent(): Webview
Get an instance of Webview
for the current webview.
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L231
Configuration for the webview to create.
2.0.0
Property | Type | Description | Defined in |
---|---|---|---|
acceptFirstMouse? | boolean | Whether 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#L745 |
allowLinkPreview? | boolean | on macOS and iOS there is a link preview on long pressing links, this is enabled by default. see https://docs.rs/objc2-web-kit/latest/objc2_web_kit/struct.WKWebView.html#method.allowsLinkPreview | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L849 |
backgroundColor? | Color | Set the window and webview background color. #### Platform-specific: - macOS / iOS: Not implemented. - Windows: - On Windows 7, alpha channel is ignored. - On Windows 8 and newer, if alpha channel is not 0 , it will be ignored. Since 2.1.0 | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L821 |
backgroundThrottling? | BackgroundThrottlingPolicy | Change the default background throttling behaviour. By default, browsers use a suspend policy that will throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when a view became minimized or hidden. This will pause all tasks until the documents visibility state changes back from hidden to visible by bringing the view back to the foreground. ## Platform-specific - Linux / Windows / Android: Unsupported. Workarounds like a pending WebLock transaction might suffice. - iOS: Supported since version 17.0+. - macOS: Supported since version 14.0+. see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578 Since 2.3.0 | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L840 |
devtools? | boolean | Whether web inspector, which is usually called browser devtools, is enabled or not. Enabled by default. This API works in debug builds, but requires devtools feature flag to enable it in release builds. #### Platform-specific - macOS: This will call private functions on macOS. - Android: Open chrome://inspect/#devices in Chrome to get the devtools window. Wry’s WebView devtools API isn’t supported on Android. - iOS: Open Safari > Develop > [Your Device Name] > [Your WebView] to get the devtools window. Since 2.1.0 | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L808 |
disableInputAccessoryView? | boolean | Allows disabling the input accessory view on iOS. The accessory view is the view that appears above the keyboard when a text input element is focused. It usually displays a view with “Done”, “Next” buttons. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L856 |
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. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L741 |
focus? | boolean | Whether the webview should have focus or not Since 2.1.0 | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L735 |
height | number | The initial height. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L723 |
incognito? | boolean | Whether 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#L757 |
javascriptDisabled? | boolean | Whether we should disable JavaScript code execution on the webview or not. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L844 |
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+. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L767 |
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 . | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L729 |
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). | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L715 |
useHttpsScheme? | boolean | Sets whether the custom protocols should use https://<scheme>.localhost instead of the default http://<scheme>.localhost on Windows and Android. Defaults to false . #### Note Using a https scheme will NOT allow mixed content when trying to fetch http endpoints and therefore will not match the behavior of the <scheme>://localhost protocols used on macOS and Linux. #### Warning Changing this value between releases will change the IndexedDB, cookies and localstorage location and your app will not be able to access them. Since 2.1.0 | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L794 |
userAgent? | string | The user agent for the webview. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L749 |
width | number | The initial width. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L721 |
x | number | The initial vertical position. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L717 |
y | number | The initial horizontal position. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L719 |
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. | Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L779 |
type Color: [number, number, number] | [number, number, number, number] | object | string;
An RGBA color. Each value has minimum of 0 and maximum of 255.
It can be either a string #ffffff
, an array of 3 or 4 elements or an object.
2.0.0
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/window.ts#L2039
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#L42
function getAllWebviews(): Promise<Webview[]>
Gets a list of instances of Webview
for all available webviews.
2.0.0
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L69
function getCurrentWebview(): Webview
Get an instance of Webview
for the current webview.
2.0.0
Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/webview.ts#L53
© 2025 Tauri Contributors. CC-BY / MIT