Webview — Embedded Browser View Control API

Webview controls the embedded browser view attached to a BrowserWindow. You create a Webview by calling win.createWebview(options) on an existing window. Each window can host one or more webviews, and a webview can display any URL, inline HTML, or content served by a custom protocol.

const webview = win.createWebview({ url: 'https://example.com' });

Keep the Webview wrapper available for as long as you need to call its methods or listen to its events. The application and owning window retain the native view and dispose it during app.exit().

Calling new Webview() directly is not supported. Create webviews through a BrowserWindow.

Creation Options

Pass a WebviewOptions object to win.createWebview().

Option	Type	Default	Description
`url`	`string`	—	URL to load when the webview is created. If both `url` and `html` are supplied, the underlying builder uses the URL.
`html`	`string`	—	Inline HTML string to render. It is ignored when `url` is supplied.
`x`	`number`	—	Left offset in logical pixels when explicit bounds are used
`y`	`number`	—	Top offset in logical pixels when explicit bounds are used
`width`	`number`	—	Initial width in physical pixels when explicit bounds are used
`height`	`number`	—	Initial height in physical pixels when explicit bounds are used
`child`	`boolean`	`false`	Build the webview as a child view within its host window
`enableDevtools`	`boolean`	`true`	Enable the browser DevTools panel
`transparent`	`boolean`	`false`	Render the webview with a transparent background
`incognito`	`boolean`	`false`	Request the backend’s private/incognito mode. Use `clearAllBrowsingData()` when you need explicit cleanup
`userAgent`	`string`	`"WebviewJS"`	Override the browser’s `User-Agent` header
`preload`	`string`	—	JavaScript string injected into every page before any page script runs
`theme`	`Theme`	—	Override the webview theme where the platform backend supports it
`hotkeysZoom`	`boolean`	`true`	Enable keyboard zoom shortcuts
`clipboard`	`boolean`	`true`	Enable clipboard access
`autoplay`	`boolean`	`true`	Allow media autoplay
`backForwardNavigationGestures`	`boolean`	`true`	Enable back/forward navigation gestures
`autoNormalizeLoadUrl`	`boolean`	`true`	On Windows, normalize registered custom-protocol URLs passed to `loadUrl()` or `loadUrlWithHeaders()` for WebView2
`useHttpsScheme`	`boolean`	`false`	On Windows, use the HTTPS form of that normalization when `autoNormalizeLoadUrl` is enabled
`ipcName`	`string`	—	Alias for the IPC global (e.g. `'bindings'` exposes `window.bindings`). `window.ipc` is always available.
`webContext`	`WebContext`	—	Shared WebContext for cookie, cache, and storage isolation
`navigationHandler`	`(url: string) => boolean`	—	Synchronous guard called before every navigation. Return `false` to cancel.

For a normal top-level webview on Windows and Linux, omit x, y, width, and height so the view fills the window and follows its size. A child: true view or any explicit bound opts into bounds mode; omitted positions default to 0, and omitted dimensions default to 800 × 600. On macOS, the native implementation builds every webview as a child view and derives initial bounds from the host window when you omit them.The native constructor receives the initial width and height as a physical size. Runtime setBounds() and the bounds getters use the backend’s logical geometry, so use setBounds() when you need logical child-view positioning or resizing.

Load new content or refresh the current page at any time:

webview.loadUrl(url: string): void
webview.loadHtml(html: string): void
webview.loadUrlWithHeaders(url: string, headers: HeaderData[]): void
webview.reload(): void
webview.url(): string | null   // currently displayed URL, or null

HeaderData shape:

interface HeaderData {
  key: string;
  value?: string;
}

On Windows, registered custom-protocol URLs are normalized to a WebView2-compatible localhost URL by default. Set autoNormalizeLoadUrl: false to disable that behavior, or set useHttpsScheme: true to use the HTTPS form of the workaround. When you provide navigationHandler in the creation options, WebviewJS calls it synchronously before every navigation attempt. Return true to allow navigation or false to block it.

const webview = win.createWebview({
  url: 'https://example.com',
  navigationHandler: (url) => {
    // Block any navigation away from example.com
    return new URL(url).hostname === 'example.com';
  },
});

Keep navigationHandler fast and do not return a Promise. The handler runs synchronously on the browser thread. A navigation event is always emitted regardless of whether navigation is allowed or cancelled.

Script Execution

Run JavaScript in the page context:

// Fire-and-forget — no return value
webview.evaluateScript(script: string): void

// Run a script and receive the stringified result in an error-first callback
webview.evaluateScriptWithCallback(
  script: string,
  callback: (err: Error | null, result: string) => void
): void

// Fire-and-forget example
webview.evaluateScript(`document.title = 'Updated by Node'`);

// Read back a value
webview.evaluateScriptWithCallback(
  `JSON.stringify({ title: document.title, url: location.href })`,
  (err, result) => {
    if (err) throw err;
    const data = JSON.parse(result);
    console.log('Page info:', data);
  }
);

Webview Events

Webview extends Node.js EventEmitter. Use .on(), .once(), .off(), .addListener(), .removeListener(), and .removeAllListeners() to manage listeners.

Event reference

Event	Payload fields	Description
`page-load-started`	`url`	The browser started loading a new page
`page-load-finished`	`url`	The page finished loading
`title-changed`	`title`	The `<title>` element changed
`download-started`	`url`	A file download started
`download-completed`	`url`, `success`	A file download completed. `success` is `true` on success
`navigation`	`url`	Fired for every navigation attempt, whether allowed or cancelled by `navigationHandler`
`new-window`	`url`	The page called `window.open()` or used `target="_blank"`. The event reports the request; `navigationHandler` can allow or deny it when provided.

Download events are observational — you cannot cancel a download from these events. On Windows, the new-window listener is observational; navigationHandler is still evaluated separately when you provide one.

Usage example

webview.on('page-load-started', ({ url }) => {
  console.log('Loading:', url);
});

webview.on('page-load-finished', ({ url }) => {
  console.log('Finished:', url);
});

webview.on('title-changed', ({ title }) => {
  win.setTitle(title ?? 'My App');
});

webview.on('download-started', ({ url }) => {
  console.log('Downloading:', url);
});

webview.on('download-completed', ({ url, success }) => {
  console.log(url, success ? 'downloaded OK' : 'FAILED');
});

webview.on('navigation', ({ url }) => {
  console.log('Navigating to:', url);
});

webview.on('new-window', ({ url }) => {
  console.log('Page wants to open:', url);
});

IPC

The page sends a message to Node by calling window.ipc.postMessage(body). Register a handler in Node with:

webview.onIpcMessage(handler: (message: IpcMessage) => void): void

IpcMessage shape:

interface IpcMessage {
  body: Buffer;           // raw message body bytes
  method: string;         // HTTP-style method string
  headers: HeaderData[];  // optional headers
  uri: string;            // request URI
}

webview.onIpcMessage((message) => {
  const text = message.body.toString('utf8');
  console.log('IPC message:', text);
});

Set ipcName: 'bindings' in WebviewOptions to also expose window.bindings as an alias for window.ipc. The default window.ipc global is always available. See the IPC Messaging guide for a complete walkthrough.

expose()

expose() is a higher-level IPC helper that makes Node.js values and functions available as a named global in the page. Every exposed function becomes a Promise-returning stub in the browser, even if the Node.js implementation is synchronous.

webview.expose(name: string, target: ExposedTarget): void

type ExposedTarget = Record<
  string,
  JsonValue | ((...args: any[]) => unknown | Promise<unknown>)
>;

Example

import { readFile } from 'node:fs/promises';

webview.expose('native', {
  appVersion: '1.0.0',            // static JSON value
  isDarkMode: true,

  readFile: async (path: string) => {
    return readFile(path, 'utf8');
  },

  writeLog: (message: string) => {
    console.log('[page]', message);
  },
});

In the page:

// Static values are available synchronously
console.log(window.native.appVersion);  // "1.0.0"

// Functions always return Promises
const content = await window.native.readFile('/etc/hostname');
await window.native.writeLog('Page loaded');

Rules and limitations

Only enumerable own data properties of target are exposed. Getters, setters, and inherited properties are ignored.
Enumerable own data properties whose values are functions become async page functions; other exposed property values are serialized with JSON.stringify. Cyclic structures, BigInt, Symbol, and an undefined top-level value throw a SerializationError. Map and Set follow normal JSON.stringify behavior, usually becoming {}; nested undefined properties are omitted.
The namespace name must be a valid JavaScript identifier and can only be exposed once per webview.

See the IPC guide for more detail and the runnable expose example.

Read and write the webview’s cookie store:

// Get all cookies, or cookies for a specific URL
webview.getCookies(url?: string): WebviewCookie[]

// Set a cookie
webview.setCookie(cookie: WebviewCookie): void

// Delete a cookie by name, optionally scoped to a domain and path
webview.deleteCookie(name: string, domain?: string, path?: string): void

// Erase all cookies, cache, local storage, and IndexedDB data
webview.clearAllBrowsingData(): void

WebviewCookie shape:

interface WebviewCookie {
  name: string;
  value: string;
  domain?: string;
  path?: string;
  httpOnly?: boolean;
  secure?: boolean;
  sameSite?: string;
}

Use "strict", "lax", or "none" for sameSite. The native mapping treats any other value as "lax".

// Set a session cookie
webview.setCookie({
  name: 'session',
  value: 'abc123',
  domain: 'example.com',
  path: '/',
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
});

// Read cookies for a URL
const cookies = webview.getCookies('https://example.com');
console.log(cookies);

// Remove a specific cookie
webview.deleteCookie('session', 'example.com', '/');

DevTools

Open, close, or check the browser developer tools:

webview.openDevtools(): void
webview.closeDevtools(): void
webview.isDevtoolsOpen(): boolean

DevTools must be enabled at creation time via enableDevtools: true in WebviewOptions.

Appearance

Set the background color shown before (or behind) page content. Each component is an integer in the range 0–255:

webview.setBackgroundColor(r: number, g: number, b: number, a: number): void

// White background
webview.setBackgroundColor(255, 255, 255, 255);

// Fully transparent
webview.setBackgroundColor(0, 0, 0, 0);

Focus

Control which element holds keyboard input:

webview.focus(): void        // give keyboard focus to the webview content area
webview.focusParent(): void  // return focus to the parent BrowserWindow

Bounds

For child or explicitly bounded webviews, you can reposition or resize the view at runtime without recreating it.

Bounds methods are most useful for child webviews created with child: true. A top-level webview created without explicit bounds tracks the host window size automatically.

The application’s window-resize handler currently reapplies the full client rectangle to every tracked webview. If a child or explicitly bounded view must keep a sub-rectangle after its host window is resized, call setBounds() again from the window’s resize listener.

webview.getBounds(): WebviewBounds | null
webview.setBounds(bounds: WebviewBounds): void

// Convenience read-only properties (logical pixels)
webview.width: number | null
webview.height: number | null
webview.x: number | null
webview.y: number | null

interface WebviewBounds {
  x: number;
  y: number;
  width: number;
  height: number;
}

// Move and resize a child webview
webview.setBounds({ x: 10, y: 60, width: 800, height: 500 });

const bounds = webview.getBounds();
console.log(bounds); // { x: 10, y: 60, width: 800, height: 500 }

Disposal

Call webview.dispose() to release a webview before app.exit():

webview.dispose(): void
webview.isDisposed(): boolean

You can also use the using declaration for automatic cleanup:

{
  using webview = win.createWebview({ url: 'https://example.com' });
  // ... use the webview ...
} // webview.dispose() called automatically

Disposal is idempotent — calling it more than once is safe. app.exit() also disposes every webview created under that application. Disposing the parent BrowserWindow also disposes all its webviews.

Core

UI & System

Types

Webview — Embedded Browser View Control API

Creation Options

Navigation

Navigation handler

Script Execution

Webview Events

Event reference

Usage example

IPC

expose()

Example

Rules and limitations

DevTools

Appearance

Focus

Bounds

Disposal

​Creation Options

​Navigation

​Navigation handler

​Script Execution

​Webview Events

​Event reference

​Usage example

​IPC

​expose()

​Example

​Rules and limitations

​Cookie Management

​DevTools

​Appearance

​Focus

​Bounds

​Disposal

Creation Options

Navigation

Navigation handler

Script Execution

Webview Events

Event reference

Usage example

IPC

expose()

Example

Rules and limitations

Cookie Management

DevTools

Appearance

Focus

Bounds

Disposal