BrowserWindow — Native OS Window Management API

BrowserWindow wraps a native OS window and provides full control over its appearance, behavior, and content. You create a BrowserWindow through the application factory — never via new BrowserWindow() directly — and then attach a Webview to it to display web content.

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

const app = new Application();
await app.whenReady();

const win = app.createBrowserWindow({ title: 'Hello', width: 1280, height: 720 });
const webview = win.createWebview({ url: 'https://example.com' });

Creation Options

Pass a BrowserWindowOptions object to app.createBrowserWindow() or app.createChildBrowserWindow().

Basic

Option	Type	Default	Description
`title`	`string`	`"WebviewJS"`	Window title bar text
`width`	`number`	`800`	Initial window width in physical pixels (or logical if `logical: true`)
`height`	`number`	`600`	Initial window height in physical pixels (or logical if `logical: true`)
`x`	`number`	—	Initial horizontal position of the window’s top-left corner
`y`	`number`	—	Initial vertical position of the window’s top-left corner
`logical`	`boolean`	`false`	When `true`, interpret `width`, `height`, `x`, and `y` as logical (CSS) pixels instead of physical pixels

Behavior

Option	Type	Default	Description
`resizable`	`boolean`	`true`	Allow the user to resize the window
`visible`	`boolean`	`true`	Show the window immediately on creation
`decorations`	`boolean`	`true`	Show the native title bar and window border
`transparent`	`boolean`	`false`	Make the window background transparent
`maximized`	`boolean`	`false`	Start the window in a maximized state
`maximizable`	`boolean`	`true`	Allow the user to maximize the window
`minimizable`	`boolean`	`true`	Allow the user to minimize the window
`focused`	`boolean`	`true`	Give the window keyboard focus on creation
`alwaysOnTop`	`boolean`	`false`	Keep the window above all other windows
`alwaysOnBottom`	`boolean`	`false`	Keep the window below all other windows
`contentProtection`	`boolean`	`false`	Prevent the window from being captured by screen-recording tools
`visibleOnAllWorkspaces`	`boolean`	`false`	Show the window on every virtual desktop / workspace

Fullscreen

Option	Type	Default	Description
`fullscreen`	`FullscreenType`	—	Start the window in fullscreen mode. `'Exclusive'` uses an exclusive display mode; `'Borderless'` is a fullscreen borderless window

Option	Type	Default	Description
`menu`	`MenuOptions`	—	Per-window menu that overrides the global application menu for this window
`showMenu`	`boolean`	—	When `true`, display the global application menu on this window

See the Menus guide for the MenuOptions shape.

Windows-specific options

Option	Type	Description
`windowsOwnerWindow`	`bigint`	HWND of the owner window
`windowsTaskbarIcon`	`TrayIconImage`	Custom taskbar icon for this window
`windowsNoRedirectionBitmap`	`boolean`	Disable the redirection bitmap (DWM)
`windowsDragAndDrop`	`boolean`	Enable OLE drag-and-drop
`windowsSkipTaskbar`	`boolean`	Hide the window from the taskbar
`windowsClassName`	`string`	Custom Win32 `WNDCLASS` name
`windowsUndecoratedShadow`	`boolean`	Add a DWM drop shadow to an undecorated window

macOS-specific options

Option	Type	Description
`macosMovableByWindowBackground`	`boolean`	Allow dragging the window by clicking its background
`macosTitlebarTransparent`	`boolean`	Make the title bar transparent
`macosTitleHidden`	`boolean`	Hide the window title text
`macosTitlebarHidden`	`boolean`	Hide the title bar entirely
`macosTitlebarButtonsHidden`	`boolean`	Hide the traffic-light buttons
`macosFullsizeContentView`	`boolean`	Extend content behind the title bar
`macosDisallowHidpi`	`boolean`	Opt out of HiDPI scaling
`macosHasShadow`	`boolean`	Toggle the window drop shadow
`macosTabbingIdentifier`	`string`	Group windows into a tab bar with this identifier

iOS-specific options

Option	Type	Description
`iosScaleFactor`	`number`	Override the display scale factor
`iosValidOrientations`	`IosValidOrientations`	Allowed device orientations (`LandscapeAndPortrait`, `Landscape`, `Portrait`)
`iosPrefersHomeIndicatorHidden`	`boolean`	Request that the home indicator be hidden
`iosDeferredSystemGestureEdges`	`number`	Bitmask of edges to defer system gestures on (top `1`, left `2`, bottom `4`, right `8`)
`iosPrefersStatusBarHidden`	`boolean`	Request that the status bar be hidden

Creating a Webview

Attach a browser view to the window by calling createWebview(). It returns a Webview object you use to control the content.

win.createWebview(options?: WebviewOptions): Webview

Hold a strong reference to the returned Webview for as long as you need it. Do not discard the wrapper into a temporary variable.

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

// ❌ Avoid — the wrapper may be garbage-collected
win.createWebview({ url: 'https://example.com' });

See Webview for the full WebviewOptions reference.

Window State Methods

Control visibility and window chrome at runtime:

win.setTitle(title: string): void
win.setVisible(visible: boolean): void
win.show(): void
win.hide(): void
win.close(): void
win.setMinimized(value: boolean): void
win.setMaximized(value: boolean): void
win.setFullscreen(type: FullscreenType | null): void  // null exits fullscreen
win.focus(): void
win.requestRedraw(): void

Size and Position

All size and position methods accept an optional logical boolean. When true, values are interpreted as logical (CSS / device-independent) pixels. When false (the default), values are physical pixels.

// Inner size: content area without the title bar and borders
win.getInnerSize(logical?: boolean): Dimensions   // { width, height }

// Outer size: full window frame including decorations
win.getOuterSize(logical?: boolean): Dimensions

// Set size; returns the new dimensions after the OS applies constraints, or null
win.setSize(width: number, height: number, logical?: boolean): Dimensions | null

// Minimum and maximum size constraints
win.setMinSize(width: number, height: number, logical?: boolean): void
win.setMaxSize(width: number, height: number, logical?: boolean): void

// Position of the window's top-left corner on screen
win.getPosition(logical?: boolean): Position      // { x, y }
win.setPosition(x: number, y: number, logical?: boolean): void

// Center on the current monitor
win.center(): void

// Current device-pixel ratio (e.g. 2.0 on a Retina display)
win.scaleFactor(): number

Divide physical pixel values by win.scaleFactor() to convert them to logical pixels, which match CSS px units in the webview.

Cursor Control

win.setCursor(cursor: CursorType): void
win.setCursorVisible(visible: boolean): void

// Position in logical pixels, relative to the window's top-left corner
win.setCursorPosition(x: number, y: number): void

// Make the window transparent to mouse input (Windows and macOS only)
win.setIgnoreCursorEvents(ignore: boolean): void

CursorType values

All 35 CursorType values are available: Default · Crosshair · Hand · Arrow · Move · Text · Wait · Help · Progress · NotAllowed · ContextMenu · Cell · VerticalText · Alias · Copy · NoDrop · Grab · Grabbing · ZoomIn · ZoomOut · ResizeEast · ResizeNorth · ResizeNorthEast · ResizeNorthWest · ResizeSouth · ResizeSouthEast · ResizeSouthWest · ResizeWest · ResizeEastWest · ResizeNorthSouth · ResizeNorthEastSouthWest · ResizeNorthWestSouthEast · ResizeColumn · ResizeRow · AllScroll

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

win.setCursor(CursorType.Hand);

Decorations and Behavior

win.setResizable(resizable: boolean): void
win.setMinimizable(minimizable: boolean): void
win.setMaximizable(maximizable: boolean): void
win.setClosable(closable: boolean): void
win.setAlwaysOnTop(always: boolean): void
win.setAlwaysOnBottom(always: boolean): void
win.setContentProtection(enabled: boolean): void
win.setDecorations(decorated: boolean): void

// Hide the window from the taskbar (Windows and Linux only)
win.setSkipTaskbar(skip: boolean): void

// Override the OS color theme for this window
win.theme: Theme           // current theme (read-only getter)
win.setTheme(theme: Theme): void

Theme values: Theme.Light, Theme.Dark, Theme.System.

Icon and Progress Bar

Window icon

Set the window’s icon from an RGBA pixel buffer:

win.setWindowIcon(icon: Uint8Array | number[], width?: number, height?: number): void
win.removeWindowIcon(): void

icon is a raw byte array of width × height × 4 bytes in RGBA order (red, green, blue, alpha, each 0–255).

Progress bar

Display a progress bar in the window’s taskbar button (Windows) or dock icon (macOS):

win.setProgressBar(progress: JsProgressBar): void

interface JsProgressBar {
  state?: ProgressBarState;
  progress?: number; // 0–100
}

`ProgressBarState`	Description
`None`	Remove the progress indicator
`Normal`	Standard progress fill
`Indeterminate`	Animated indeterminate spinner
`Paused`	Paused / yellow state
`Error`	Error / red state

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

win.setProgressBar({ state: ProgressBarState.Normal, progress: 42 });

File Dialogs

Open a native file picker and get the selected paths. This call blocks until the user dismisses the dialog and returns the selected paths synchronously:

win.openFileDialog(options?: FileDialogOptions): string[]

interface FileDialogOptions {
  multiple?: boolean;             // Allow selecting more than one file
  title?: string;                 // Dialog title
  defaultPath?: string;           // Initial directory or file path
  filters?: Array<{
    name: string;                 // e.g. "Images"
    extensions: string[];         // e.g. ["png", "jpg", "webp"]
  }>;
}

const paths = win.openFileDialog({
  multiple: true,
  title: 'Open images',
  filters: [{ name: 'Images', extensions: ['png', 'jpg', 'webp'] }],
});
console.log(paths); // ['/home/user/photo.png', ...]

Monitor Info

Query information about the displays attached to the system:

win.currentMonitor(): Monitor | null    // monitor the window is currently on
win.primaryMonitor(): Monitor | null    // the system's primary monitor
win.availableMonitors(): Monitor[]      // all connected monitors

Each Monitor object has:

interface Monitor {
  name?: string;
  scaleFactor: number;
  size: Dimensions;            // { width, height } in physical pixels
  position: Position;          // { x, y } relative to the virtual screen
  videoModes: VideoMode[];     // available resolution/refresh-rate combinations
}

Custom Protocols

Register a URL-scheme handler to serve your own content to the webview. You must call registerProtocol() before calling createWebview() on the same window.

win.registerProtocol(
  name: string,
  handler: (request: Request) => Response | CustomProtocolResponse | Promise<Response | CustomProtocolResponse>
): void

The handler receives a standard Fetch API Request and should return a standard Response (compatible with Hono, itty-router, and any Fetch-API framework) or a legacy CustomProtocolResponse plain object.

// Serve a local file tree under app://localhost/
win.registerProtocol('app', async (request) => {
  const url = new URL(request.url);
  const body = await readFile('./dist' + url.pathname);
  return new Response(body, {
    headers: { 'Content-Type': 'text/html' },
  });
});

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

See the Custom Protocols guide for a complete walkthrough.

State Properties

Read the current window state through these properties and methods:

win.width: number        // inner width in physical pixels
win.height: number       // inner height in physical pixels
win.x: number            // outer x position in physical pixels
win.y: number            // outer y position in physical pixels
win.title: string        // current window title

win.isFocused(): boolean
win.isVisible(): boolean
win.isDecorated(): boolean
win.isClosable(): boolean
win.isMaximizable(): boolean
win.isMinimizable(): boolean
win.isMaximized(): boolean
win.isMinimized(): boolean
win.isResizable(): boolean

Window Events

BrowserWindow extends Node.js EventEmitter. All positional values (x, y, width, height, deltaX, deltaY) are in physical pixels at the current DPI. Divide by win.scaleFactor() to convert to logical (CSS) pixels.

Event reference

Event	Payload fields	Description
`move`	`x`, `y`	Window moved to a new position
`resize`	`width`, `height`	Window was resized
`close`	—	Window received a close request
`focus`	—	Window gained keyboard focus
`blur`	—	Window lost keyboard focus
`mouse-enter`	`x`, `y`	Pointer entered the window
`mouse-leave`	—	Pointer left the window
`mouse-move`	`x`, `y`	Pointer moved inside the window
`mouse-down`	`x`, `y`, `button`	Mouse button pressed (`0`=left, `1`=middle, `2`=right)
`mouse-up`	`x`, `y`, `button`	Mouse button released
`scroll`	`deltaX`, `deltaY`	Scroll or trackpad gesture. Physical device deltas are passed through; line-scroll deltas are multiplied by 20
`key-down`	`key`, `code`, `modifiers`, `isRepeat`	Key pressed. `modifiers`: `1`=Shift, `2`=Ctrl, `4`=Alt, `8`=Meta
`key-up`	`key`, `code`, `modifiers`, `isRepeat`	Key released
`file-drop`	`files`	Files dropped onto the window
`file-hover`	`files`	Files dragged over the window
`file-hover-cancelled`	—	File drag left the window without a drop
`scale-factor-changed`	`scaleFactor`	DPI scale factor changed
`theme-changed`	`text` (`'light'` \| `'dark'`)	OS theme changed
`ime`	`text`, `phase`	IME input event. Phases: `enabled`, `preedit`, `commit`, `disabled`
`touch`	`x`, `y`, `touchId`, `phase`	Touch event. Phases: `started`, `moved`, `ended`, `cancelled`

Usage example

win.on('resize', ({ width, height }) => {
  console.log(`Window resized to ${width}×${height} (physical px)`);
});

win.on('key-down', ({ key, code, modifiers, isRepeat }) => {
  if (key === 'F5') webview.reload();
});

win.on('file-drop', ({ files }) => {
  console.log('Dropped files:', files);
});

win.on('close', () => {
  app.exit();
});

win.on('theme-changed', ({ text }) => {
  console.log(`System theme is now: ${text}`);
});

win.on('mouse-down', ({ x, y, button }) => {
  const logical = { x: x / win.scaleFactor(), y: y / win.scaleFactor() };
  console.log(`Button ${button} at logical (${logical.x}, ${logical.y})`);
});

Identity and Native Handles

win.id(): number        // stable numeric ID within this process
win.isChild: boolean    // true if created with createChildBrowserWindow()
win.getNativeHandle(): bigint

getNativeHandle() returns the platform-native handle as a bigint pointer value:

Platform	Handle type
Windows	`HWND`
macOS	`NSView`
X11	`XID`
Wayland	`wl_surface`

Returns 0n when no supported handle is available for the current platform. Treat this as a borrowed value — do not destroy it or pass ownership to native code.

Platform-Specific Extensions

Windows

win.setEnable(enabled: boolean): void
win.setTaskbarIcon(icon: Uint8Array | number[], width?: number, height?: number): void
win.removeTaskbarIcon(): void
win.setUndecoratedShadow(shadow: boolean): void
win.getNativeHandleAnyThread(): bigint

macOS

win.simpleFullscreen(): boolean
win.setSimpleFullscreen(fullscreen: boolean): boolean
win.hasShadow(): boolean
win.setHasShadow(value: boolean): void
win.setTabbingIdentifier(identifier: string): void
win.tabbingIdentifier(): string
win.isDocumentEdited(): boolean
win.setDocumentEdited(edited: boolean): void

Linux (Wayland)

win.getWaylandSurface(): bigint  // returns 0n on non-Wayland platforms

Android

win.androidContentRect(): AndroidContentRect  // { left, top, right, bottom }
win.androidConfig(): string                   // diagnostic configuration string

Disposal

Call win.dispose() when you want to release a window before app.exit():

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

You can also use the using declaration for automatic cleanup:

{
  using win = app.createBrowserWindow({ title: 'Temporary' });
  // ... use the window ...
} // win.dispose() called automatically

Disposal is idempotent — calling it more than once is safe. Disposing a window also disposes all Webview instances attached to it. app.exit() disposes every window owned by the application.

Core

UI & System

Types

BrowserWindow — Native OS Window Management API

Creation Options

Basic

Behavior

Fullscreen

Menu

Windows-specific options

macOS-specific options

iOS-specific options

Creating a Webview

Window State Methods

Size and Position

Cursor Control

CursorType values

Decorations and Behavior

Icon and Progress Bar

Window icon

Progress bar

File Dialogs

Monitor Info

Custom Protocols

State Properties

Window Events

Event reference

Usage example

Identity and Native Handles

Platform-Specific Extensions

Windows

macOS

Linux (Wayland)

Android

Disposal

​Creation Options

​Basic

​Behavior

​Fullscreen

​Menu

​Windows-specific options

​macOS-specific options

​iOS-specific options

​Creating a Webview

​Window State Methods

​Size and Position

​Cursor Control

​CursorType values

​Decorations and Behavior

​Icon and Progress Bar

​Window icon

​Progress bar

​File Dialogs

​Monitor Info

​Custom Protocols

​State Properties

​Window Events

​Event reference

​Usage example

​Identity and Native Handles

​Platform-Specific Extensions

​Windows

​macOS

​Linux (Wayland)

​Android

​Disposal

Creation Options

Basic

Behavior

Fullscreen

Menu

Windows-specific options

macOS-specific options

iOS-specific options

Creating a Webview

Window State Methods

Size and Position

Cursor Control

CursorType values

Decorations and Behavior

Icon and Progress Bar

Window icon

Progress bar

File Dialogs

Monitor Info

Custom Protocols

State Properties

Window Events

Event reference

Usage example

Identity and Native Handles

Platform-Specific Extensions

Windows

macOS

Linux (Wayland)

Android

Disposal