WebviewJS on Windows: WebView2, Taskbar and Win32 APIs

WebviewJS on Windows uses Microsoft’s WebView2 engine — a Chromium-based runtime that ships with Microsoft Edge. Because WebView2 is maintained by Microsoft and updated alongside Edge, you always get a modern, standards-compliant browser surface without bundling Chromium yourself.

Prerequisites

Windows 11 ships with the WebView2 runtime pre-installed. Windows 10 auto-downloads and installs it the first time it is needed. You can also pre-install it manually using the Evergreen bootstrapper from Microsoft.

Check the installed WebView2 version at runtime:

import { getWebviewVersion } from '@webviewjs/webview';

console.log(getWebviewVersion()); // e.g. "128.0.2739.42"

Supported architectures

Target triple	Architecture	CI
`x86_64-pc-windows-msvc`	x64	✅
`i686-pc-windows-msvc`	x86 (32-bit)	✅
`aarch64-pc-windows-msvc`	arm64	✅

Windows-specific creation options

Pass these fields in the BrowserWindowOptions object when calling app.createBrowserWindow(). They are silently ignored on other platforms.

Option	Type	Description
`windowsOwnerWindow`	`bigint`	HWND of a parent window. Makes this window a child of the specified Win32 window.
`windowsTaskbarIcon`	`TrayIconImage`	Custom icon shown in the taskbar button at window creation time.
`windowsNoRedirectionBitmap`	`boolean`	Disables the redirection surface (DWM bitmap). Useful for transparent or layered windows.
`windowsDragAndDrop`	`boolean`	Enables OLE drag-and-drop support on the window.
`windowsSkipTaskbar`	`boolean`	Hides the window from the taskbar and Alt+Tab switcher at creation time.
`windowsClassName`	`string`	Win32 window class name registered for this window. Useful for shell integrations that query `WM_CLASS`.
`windowsUndecoratedShadow`	`boolean`	Adds a drop shadow to a borderless (`decorations: false`) window using DWM.

import { Application } from '@webviewjs/webview';

const app = new Application();

app.whenReady().then(() => {
  const win = app.createBrowserWindow({
    decorations: false,
    windowsUndecoratedShadow: true,
    windowsClassName: 'MyAppWindow',
    windowsSkipTaskbar: false,
  });

  win.createWebview({ url: 'app://localhost/index.html' });
});

Windows runtime methods

These methods are Windows-specific and safe to call on any platform — they return neutral values or do nothing outside Windows.

// Enable or disable user input for the window (grays out the window when disabled)
win.setEnable(false);
win.setEnable(true);

// Replace the taskbar button icon at runtime
// data is an RGBA Buffer; width and height default to sqrt(data.length / 4)
win.setTaskbarIcon(rgbaBuffer, 32, 32);

// Remove the custom taskbar icon and restore the default window icon
win.removeTaskbarIcon();

// Toggle DWM drop shadow on a borderless window
win.setUndecoratedShadow(true);

// Retrieve the native HWND handle as a bigint
// Safe to call from any thread (unlike getNativeHandle())
const hwnd = win.getNativeHandleAnyThread();
console.log(hwnd); // e.g. 133143624n

Progress bar

Integrate with the Windows taskbar progress indicator:

import { ProgressBarState } from '@webviewjs/webview';

// Show a determinate progress ring at 42 %
win.setProgressBar({ state: ProgressBarState.Normal, progress: 42 });

// Show an indeterminate spinner
win.setProgressBar({ state: ProgressBarState.Indeterminate });

// Signal an error state (red bar)
win.setProgressBar({ state: ProgressBarState.Error, progress: 100 });

// Remove the progress indicator
win.setProgressBar({ state: ProgressBarState.None });

ProgressBarState values: None · Normal · Indeterminate · Paused · Error

IPC on Windows

In wry 0.53, a file: page that calls window.ipc.postMessage() can abort because WebView2 treats the page source as a file: URI and wry attempts to convert it to an HTTP request URI. Always load IPC-enabled pages through a custom protocol such as app:// — never via a file: URL. See the Custom Protocols guide for setup instructions.

// Register your protocol before creating the webview
win.registerProtocol('app', async (request) => {
  // serve files from ./dist
  const filePath = join(process.cwd(), 'dist', new URL(request.url).pathname);
  return new Response(await readFile(filePath), {
    headers: { 'Content-Type': 'text/html; charset=utf-8' },
  });
});

// Load from the custom protocol — IPC works correctly
win.createWebview({ url: 'app://localhost/index.html' });

On Windows the menu bar is attached to each window’s title bar following standard Win32 behaviour. Every window can carry its own independent menu or share the application-level menu set via app.setMenu().

const win = app.createBrowserWindow({
  title: 'My App',
  menu: {
    items: [
      {
        label: 'File',
        submenu: {
          items: [
            { id: 'new',  label: 'New',  accelerator: 'Ctrl+N' },
            { id: 'open', label: 'Open', accelerator: 'Ctrl+O' },
            { role: 'separator' },
            { id: 'quit', label: 'Exit', accelerator: 'Alt+F4' },
          ],
        },
      },
    ],
  },
});

Listen for custom menu item clicks on the Application instance:

app.on('custom-menu-click', ({ customMenuEvent }) => {
  if (customMenuEvent.id === 'quit') app.exit();
});

DPI and HiDPI scaling

Tao reads the monitor’s scale factor automatically and reports it via win.scaleFactor(). Use logical pixels when positioning child elements:

const dpr = win.scaleFactor();
const { width, height } = win.getInnerSize(/* logical = */ true);

All values from window events (resize, move, mouse-move, etc.) arrive in physical pixels. Divide by win.scaleFactor() to convert to logical (CSS) pixels.

Get Started

Guides

Platform Notes

WebviewJS on Windows: WebView2, Taskbar and Win32 APIs

Prerequisites

Supported architectures

Windows-specific creation options

Windows runtime methods

Progress bar

IPC on Windows

Menu bar

DPI and HiDPI scaling

​Prerequisites

​Supported architectures

​Windows-specific creation options

​Windows runtime methods

​Progress bar

​IPC on Windows

​Menu bar

​DPI and HiDPI scaling

Prerequisites

Supported architectures

Windows-specific creation options

Windows runtime methods

Progress bar

IPC on Windows

Menu bar

DPI and HiDPI scaling