Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/webviewjs/webview/llms.txt

Use this file to discover all available pages before exploring further.

WebviewJS on Windows is powered by WebView2, Microsoft’s Chromium-based embedding engine, which means your users get a modern, evergreen browser runtime without shipping a full browser bundle. The engine integrates tightly with the Win32 windowing layer through Tao, giving you native DPI awareness, taskbar badge support, and per-window content protection — all exposed through a clean JavaScript API.

​
WebView2 Runtime

WebView2 is the rendering engine WebviewJS uses on Windows. It ships pre-installed on Windows 11 and is automatically downloaded and installed the first time it is needed on Windows 10. For enterprise or offline deployments you can pre-install it using Microsoft’s Evergreen bootstrapper.

Windows 11

WebView2 runtime ships pre-installed with the OS. No additional setup required.

Windows 10

The runtime is auto-downloaded on first use. You may also pre-install it via the Evergreen bootstrapper.
You can read the installed WebView2 version at runtime: 
import { getWebviewVersion } from '@webviewjs/webview';

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

​
Windows-Specific Window Options

BrowserWindowOptions includes several Windows-only fields that map directly onto the underlying Win32/Tao builder: 
import { Application } from '@webviewjs/webview';

const app = new Application();
const win = app.createBrowserWindow({
  // Attach this window to an existing HWND owner (for tool/popup windows)
  windowsOwnerWindow: parentHwnd,

  // Set a custom taskbar icon distinct from the window icon
  windowsTaskbarIcon: { data: iconBuffer, width: 32, height: 32 },

  // Disable DirectComposition redirection bitmap (useful for layered windows)
  windowsNoRedirectionBitmap: true,

  // Enable OLE drag-and-drop support
  windowsDragAndDrop: true,

  // Omit the window from the taskbar (e.g. system-tray-only apps)
  windowsSkipTaskbar: false,

  // Override the Win32 WNDCLASSEX class name
  windowsClassName: 'MyAppWindowClass',

  // Show a drop-shadow on undecorated (borderless) windows
  windowsUndecoratedShadow: true,
});

​
Option Reference

OptionTypeDescription
windowsOwnerWindowbigintHWND of the owner window for modal/popup positioning
windowsTaskbarIconTrayIconImageCustom icon shown in the taskbar button
windowsNoRedirectionBitmapbooleanDisables the DirectComposition redirection bitmap
windowsDragAndDropbooleanEnables OLE drag-and-drop message handling
windowsSkipTaskbarbooleanHides the window from the taskbar
windowsClassNamestringCustom Win32 window class name
windowsUndecoratedShadowbooleanRenders a drop-shadow on borderless windows

​
DPI and Scale Factor

Tao is DPI-aware and reports the monitor’s scale factor automatically. Use win.scaleFactor() to get the current ratio, and always work in logical pixels when positioning child elements or calculating layout: 
const scale = win.scaleFactor(); // e.g. 1.5 for 150% DPI
console.log(`Scale factor: ${scale}`);

// Set window size in logical pixels
win.setSize(800, 600, /* logical */ true);
Pass logical: true to BrowserWindowOptions or setSize() / setPosition() to work in logical pixels. Physical pixels are the default.

​
Taskbar Icons

You can set or remove a dedicated taskbar icon independently of the window’s title-bar icon: 
import { readFileSync } from 'node:fs';

const iconData = readFileSync('./assets/taskbar-icon.png');

// Set a custom taskbar icon
win.setTaskbarIcon(iconData);

// Remove the custom taskbar icon
win.removeTaskbarIcon();
Both methods accept raw Uint8Array / Buffer pixel data. You may also supply explicit width and height if the buffer contains raw RGBA bytes rather than an encoded image: 
win.setTaskbarIcon(rgbaBuffer, 32, 32);

​
Progress Bar

WebviewJS exposes WebView2’s taskbar progress overlay through setProgressBar(). Pass a JsProgressBar object with an optional state and a progress value (0–100): 
import { ProgressBarState } from '@webviewjs/webview';

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

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

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

// Clear the progress overlay
win.setProgressBar({ state: ProgressBarState.None });

​
ProgressBarState Values

StateDescription
NoneRemoves the progress overlay
NormalGreen progress bar at progress %
IndeterminateAnimated spinner (ignores progress)
PausedYellow/paused bar
ErrorRed error indicator

​
Content Protection

Prevent window contents from appearing in screenshots, screen recordings, or the Windows task switcher: 
// Enable content protection
win.setContentProtection(true);

// Disable it later
win.setContentProtection(false);
contentProtection can also be set at window creation time via BrowserWindowOptions. However, it cannot be toggled at runtime on all driver configurations — prefer setting it at creation for reliability.

​
IPC and Custom Protocols

On Windows, a file: page that calls window.ipc.postMessage() can abort. WebView2 reports the page origin as a file: URI and wry attempts to convert it to an HTTP request URI, which fails.
Always serve pages that use IPC or webview.expose() via a custom protocol rather than file: URLs. Register a custom protocol through the BrowserWindow low-level API and then load content from it: 
// Load via a custom protocol — IPC works correctly
webview.loadUrl('app://localhost/index.html');
On Windows the menu bar is attached to each window’s title bar (standard Win32 behaviour). Each window can carry its own menu, or inherit the global one set via app.setMenu(): 
app.setMenu({
  items: [
    {
      label: 'File',
      submenu: { items: [{ label: 'Exit', role: 'quit' }] },
    },
  ],
});

​
Undecorated Windows and Shadows

When decorations: false is set, Windows will strip the title bar but also removes the drop shadow by default. Re-enable it with windowsUndecoratedShadow: 
const win = app.createBrowserWindow({
  decorations: false,
  windowsUndecoratedShadow: true,
  transparent: true,
});
Combine transparent: true with windowsUndecoratedShadow: true for a modern frameless window that still has the native drop shadow. Transparency must be set at creation time and cannot be changed at runtime.

Build docs developers (and LLMs) love

Get started for freeTalk to us