BrowserWindow: OS Window Management & Configuration

BrowserWindow represents a native OS window managed by Tao. You never instantiate it directly — create one via app.createBrowserWindow() or app.createChildBrowserWindow(). Once you have a window you can attach a Webview to it, subscribe to input and lifecycle events, and adjust every aspect of the window’s appearance and behavior at runtime.

Keep the BrowserWindow reference alive for as long as the window should exist. app.exit() disposes every window owned by the application; call win.dispose() for earlier cleanup.

Creation Options

Pass these to app.createBrowserWindow(options):

interface BrowserWindowOptions {
  title?: string;
  width?: number;
  height?: number;
  x?: number;
  y?: number;
  logical?: boolean;
  resizable?: boolean;
  visible?: boolean;
  decorations?: boolean;
  transparent?: boolean;
  maximized?: boolean;
  maximizable?: boolean;
  minimizable?: boolean;
  focused?: boolean;
  alwaysOnTop?: boolean;
  alwaysOnBottom?: boolean;
  contentProtection?: boolean;
  visibleOnAllWorkspaces?: boolean;
  fullscreen?: FullscreenType;
  menu?: MenuOptions;
  showMenu?: boolean;
}

General Options

title

string

default:"WebviewJS"

Window title shown in the title bar and taskbar.

width

number

default:"800"

Initial window width in physical pixels (or logical if logical: true).

height

number

default:"600"

Initial window height in physical pixels (or logical if logical: true).

number

Initial left (x) position of the window.

number

Initial top (y) position of the window.

logical

boolean

When true, width, height, x, and y are interpreted as logical (CSS/DPI-independent) pixels instead of physical pixels.

resizable

boolean

default:"true"

Whether the user can resize the window.

visible

boolean

default:"true"

Whether the window is initially visible.

decorations

boolean

default:"true"

Show the native title bar and border. Set to false for a fully custom-drawn chrome.

transparent

boolean

default:"false"

Enable a transparent window background. Requires decorations: false on most platforms.

maximized

boolean

default:"false"

Start the window in a maximized state.

maximizable

boolean

default:"true"

Allow the user to maximize the window.

minimizable

boolean

default:"true"

Allow the user to minimize the window.

focused

boolean

default:"true"

Give the window keyboard focus when it opens.

alwaysOnTop

boolean

default:"false"

Keep the window above all other windows.

alwaysOnBottom

boolean

Keep the window below all other windows (useful for desktop widgets).

contentProtection

boolean

Prevent the window content from appearing in screenshots or screen recordings.

visibleOnAllWorkspaces

boolean

Show the window on all virtual desktops / workspaces (macOS and Linux).

fullscreen

FullscreenType

Initial fullscreen mode. FullscreenType.Exclusive (0) or FullscreenType.Borderless (1).

Per-window menu, overrides the global application menu for this window.

Show the global application menu on this specific window.

Windows-Specific Options

windowsOwnerWindow

bigint

HWND of the owner window, for creating owned/popup windows on Windows.

windowsTaskbarIcon

TrayIconImage

Custom taskbar icon { data: Buffer, width?: number, height?: number }.

windowsNoRedirectionBitmap

boolean

Disable the Windows redirection bitmap (DirectComposition layered windows).

windowsDragAndDrop

boolean

Enable native OLE drag-and-drop support.

windowsSkipTaskbar

boolean

Omit the window from the Windows taskbar.

windowsClassName

string

Custom Win32 window class name registered with RegisterClassEx.

windowsUndecoratedShadow

boolean

Draw a native drop shadow for undecorated (decorations: false) windows.

macOS-Specific Options

macosMovableByWindowBackground

boolean

Allow the window to be dragged by clicking on its background content area.

macosTitlebarTransparent

boolean

Make the title bar background transparent so content can extend beneath it.

macosTitleHidden

boolean

Hide the window title text while keeping the title bar chrome.

macosTitlebarHidden

boolean

Hide the entire title bar, giving a full-height content area.

macosTitlebarButtonsHidden

boolean

Hide the traffic-light (close/minimize/maximize) buttons.

macosFullsizeContentView

boolean

Extend content under the title bar for full-bleed layouts.

macosDisallowHidpi

boolean

Force 1× pixel density even on HiDPI/Retina displays.

macosHasShadow

boolean

Control the macOS window drop shadow (default: platform default).

macosTabbingIdentifier

string

Group windows into macOS native tabs by assigning the same identifier.

iOS-Specific Options

iosScaleFactor

number

Override the screen scale factor for the window.

iosValidOrientations

IosValidOrientations

Allowed screen orientations. LandscapeAndPortrait (0), Landscape (1), or Portrait (2).

iosPrefersHomeIndicatorHidden

boolean

Request that the home indicator be hidden.

iosDeferredSystemGestureEdges

number

Bitmask of edges that defer system gestures: top 1, left 2, bottom 4, right 8.

iosPrefersStatusBarHidden

boolean

Request that the status bar be hidden.

Webview Creation

`createWebview(options?, webContext?)`

Attach a webview to this window. Returns a Webview instance that you must keep in application state.

win.createWebview(
  options?: WebviewOptions,
  webContext?: WebContext
): Webview

options

WebviewOptions

See Webview options for all fields.

webContext

WebContext

A WebContext created via app.createWebContext() to share cookie and storage data across webviews.

returns

Webview

The new Webview instance. Do not discard this reference.

`registerProtocol(name, handler)`

Register a URL-scheme handler on this window before calling createWebview(). The handler receives a Fetch API Request and should return a Response (or a legacy CustomProtocolResponse plain object).

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

name

string

required

The scheme name, e.g. 'app' to handle app://… URLs.

handler

function

required

Called for every request matching the scheme. Compatible with Hono, itty-router, and any Fetch-API framework.

win.registerProtocol('app', async (req) => {
  const body = await readFile('./dist/index.html');
  return new Response(body, {
    headers: { 'Content-Type': 'text/html' },
  });
});

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

Window State

Visibility & lifecycle

win.setTitle(title: string): void
win.setVisible(visible: boolean): void
win.show(): void
win.hide(): void
win.close(): void    // triggers window-close-requested
win.focus(): void
win.requestRedraw(): void

title

string

New window title string.

`title` getter

win.title: string

Returns the current window title.

Minimize / Maximize / Fullscreen

win.setMinimized(value: boolean): void
win.setMaximized(value: boolean): void
win.setFullscreen(type?: FullscreenType | null): void
win.fullscreen: FullscreenType | null   // getter

Pass null to setFullscreen to exit fullscreen.

State predicates

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

State setters

win.setClosable(closable: boolean): void
win.setMaximizable(maximizable: boolean): void
win.setMinimizable(minimizable: boolean): void
win.setResizable(resizable: boolean): void

`isChild` getter

win.isChild: boolean

true for windows created via app.createChildBrowserWindow().

`id()`

win.id(): number

Stable numeric identifier for this window within the current process.

`hasMenu()`

win.hasMenu(): boolean

Returns true if the window currently has a menu attached.

Size & Position

All size and position methods accept an optional logical boolean. When true, values are in logical (DPI-independent) pixels; when false (the default), values are in physical pixels.

Inner and outer dimensions

win.getInnerSize(logical?: boolean): Dimensions   // content area
win.getOuterSize(logical?: boolean): Dimensions   // including title bar & borders

returns

Dimensions

{ width: number, height: number }

`setSize(width, height, logical?)`

win.setSize(width: number, height: number, logical?: boolean): Dimensions | null

Resize the window. Returns the new inner dimensions, or null if the change was rejected by the platform.

Min / Max constraints

win.setMinSize(width: number, height: number, logical?: boolean): void
win.setMaxSize(width: number, height: number, logical?: boolean): void

Position

win.getPosition(logical?: boolean): Position   // { x, y }
win.setPosition(x: number, y: number, logical?: boolean): void
win.center(): void   // center on current monitor

Dimension getters (physical pixels)

win.width: number    // inner width
win.height: number   // inner height
win.x: number        // outer x position
win.y: number        // outer y position

`scaleFactor()`

win.scaleFactor(): number

Device-pixel ratio for the monitor the window is currently on. Divide physical pixel values by this to obtain logical (CSS) pixels.

Visual Appearance

Decorations & layering

win.setDecorations(enabled: boolean): void
win.setAlwaysOnTop(enabled: boolean): void
win.setAlwaysOnBottom(enabled: boolean): void
win.setContentProtection(enabled: boolean): void
win.setSkipTaskbar(skip: boolean): void     // Windows and Linux
win.setEnable(enabled: boolean): void       // Windows: enable/disable input

Theme

win.theme: Theme                // getter — Theme.Light (0), Theme.Dark (1), Theme.System (2)
win.setTheme(theme: Theme): void

Icons

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

Pass raw RGBA pixel data with the corresponding pixel dimensions.

Progress bar

win.setProgressBar(state: JsProgressBar): void

state

JsProgressBar

required

Show JsProgressBar

state

ProgressBarState

None (0), Normal (1), Indeterminate (2), Paused (3), or Error (4).

progress

number

Progress value from 0 to 100.

Shadow (Windows undecorated)

win.setUndecoratedShadow(shadow: boolean): void

Cursor

win.setCursor(cursor: CursorType): void
win.setCursorVisible(visible: boolean): void
win.setCursorPosition(x: number, y: number): void   // logical px, relative to window
win.setIgnoreCursorEvents(ignore: boolean): void    // click-through (Windows/macOS)

CursorType values: 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.

File Dialogs

`openFileDialog(options?)`

win.openFileDialog(options?: FileDialogOptions): Array<string>

options

FileDialogOptions

Show FileDialogOptions

multiple

boolean

Allow selecting multiple files.

title

string

Dialog title text.

defaultPath

string

Initial directory or file path.

filters

FileFilter[]

Array of { name: string, extensions: string[] } file-type filters.

returns

Array<string>

Array of absolute file paths selected by the user, or an empty array if cancelled.

const files = win.openFileDialog({
  multiple: true,
  title: 'Open images',
  filters: [{ name: 'Images', extensions: ['png', 'jpg', 'gif'] }],
});
console.log(files);

Monitors

win.getAvailableMonitors(): Monitor[]
win.getCurrentMonitor(): Monitor | null
win.getPrimaryMonitor(): Monitor | null
win.getMonitorFromPoint(x: number, y: number): Monitor | null

Monitor

object

Show Monitor

name

string | undefined

Display name, if available.

scaleFactor

number

DPI scale factor.

size

Dimensions

{ width, height } in physical pixels.

position

Position

{ x, y } position of the monitor’s top-left corner.

videoModes

VideoMode[]

Available video modes { size, bitDepth, refreshRate }.

Platform-Specific Extensions

Identity & native handles

win.getNativeHandle(): bigint
win.getNativeHandleAnyThread(): bigint

getNativeHandle() returns the platform-native handle as a bigint pointer: HWND on Windows, NSView on macOS, XID on X11, or a wl_surface pointer on Wayland. Returns 0n when no supported handle is available. Treat as a borrowed reference — do not destroy it. getNativeHandleAnyThread() is the Windows-specific variant safe to call from non-main threads.

macOS runtime extensions

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 runtime extensions

win.getWaylandSurface(): bigint

Returns the native Wayland surface pointer, or 0n when not on Wayland.

iOS runtime extensions

win.setIosScaleFactor(value: number): void
win.setValidOrientations(value: IosValidOrientations): void
win.setPrefersHomeIndicatorHidden(value: boolean): void
win.setPreferredScreenEdgesDeferringSystemGestures(edges: number): void
win.setPrefersStatusBarHidden(value: boolean): void

Screen edges bitmask: top 1, left 2, bottom 4, right 8.

Android runtime extensions

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

Runtime methods called on an unsupported platform return neutral values or do nothing — they do not throw.

Events

BrowserWindow extends Node.js EventEmitter with a fully typed event map. Use .on(), .once(), .off(), and .removeAllListeners(). 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	Payload	Description
`move`	`{ event, x, y }`	Window moved
`resize`	`{ event, width, height }`	Window resized
`close`	`{ event }`	Window close requested
`focus`	`{ event }`	Window gained focus
`blur`	`{ event }`	Window lost focus
`mouse-enter`	`{ event, x, y }`	Cursor entered window
`mouse-leave`	`{ event }`	Cursor left window
`mouse-move`	`{ event, x, y }`	Cursor moved inside window
`mouse-down`	`{ event, x, y, button }`	Mouse button pressed (0=left, 1=middle, 2=right)
`mouse-up`	`{ event, x, y, button }`	Mouse button released
`scroll`	`{ event, deltaX, deltaY }`	Scroll/wheel input
`key-down`	`{ event, key, code, modifiers, isRepeat }`	Key pressed
`key-up`	`{ event, key, code, modifiers, isRepeat }`	Key released
`file-drop`	`{ event, files }`	Files dropped onto window
`file-hover`	`{ event, files }`	Files dragged over window
`file-hover-cancelled`	`{ event }`	Drag cancelled
`scale-factor-changed`	`{ event, scaleFactor }`	DPI changed
`theme-changed`	`{ event, text }`	OS theme changed (`"light"` or `"dark"`)
`ime`	`{ event, text, phase }`	IME composition (phases: `enabled`, `preedit`, `commit`, `disabled`)
`touch`	`{ event, x, y, touchId, phase }`	Touch input (phases: `started`, `moved`, `ended`, `cancelled`)

Scroll deltas from a pixel-precise trackpad are passed through as-is; line-scroll deltas (mouse wheel) are multiplied by 20 to produce an equivalent pixel distance. Modifier bitmask for key events: 1=Shift, 2=Ctrl, 4=Alt, 8=Meta/Super/Command.

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

const app = new Application();
const win = app.createBrowserWindow({ title: 'Event demo', width: 900, height: 600 });

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

win.on('key-down', ({ key, code, modifiers, isRepeat }) => {
  if (!isRepeat) console.log(`Key: ${key} (${code}), modifiers: ${modifiers}`);
});

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

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

app.on('application-close-requested', () => app.exit());
app.run();

Windows created with { decorations: false, resizable: true } use Tao’s native platform behaviour for drag-resize — no extra code is required.

Disposal

win.dispose(): void
win.isDisposed(): boolean
win[Symbol.dispose](): void

Call win.dispose() for early cleanup. Disposal is idempotent. Disposing a window also disposes all webviews attached to it. Use Symbol.dispose with using for automatic cleanup:

{
  using win = app.createBrowserWindow({ title: 'Short-lived', width: 400, height: 300 });
  win.createWebview({ html: '<p>Temporary</p>' });
  // win.dispose() called automatically at block exit
}

Core

UI & Notifications

Reference

Documentation Index

​Creation Options

​General Options

​Windows-Specific Options

​macOS-Specific Options

​iOS-Specific Options

​Webview Creation

​createWebview(options?, webContext?)

​registerProtocol(name, handler)

​Window State

​Visibility & lifecycle

​title getter

​Minimize / Maximize / Fullscreen

​State predicates

​State setters

​isChild getter

​id()

​hasMenu()

​Size & Position

​Inner and outer dimensions

​setSize(width, height, logical?)

​Min / Max constraints

​Position

​Dimension getters (physical pixels)

​scaleFactor()

​Visual Appearance

​Decorations & layering

​Theme

​Icons

​Progress bar

​Shadow (Windows undecorated)

​Cursor

​File Dialogs

​openFileDialog(options?)

​Monitors

​Platform-Specific Extensions

​Identity & native handles

​macOS runtime extensions

​Linux runtime extensions

​iOS runtime extensions

​Android runtime extensions

​Events

​Disposal

Build docs developers (and LLMs) love

Creation Options

General Options

Windows-Specific Options

macOS-Specific Options

iOS-Specific Options

Webview Creation

`createWebview(options?, webContext?)`

`registerProtocol(name, handler)`

Window State

Visibility & lifecycle

`title` getter

Minimize / Maximize / Fullscreen

State predicates

State setters

`isChild` getter

`id()`

`hasMenu()`

Size & Position

Inner and outer dimensions

`setSize(width, height, logical?)`

Min / Max constraints

Position

Dimension getters (physical pixels)

`scaleFactor()`

Visual Appearance

Decorations & layering

Theme

Icons

Progress bar

Shadow (Windows undecorated)

Cursor

File Dialogs

`openFileDialog(options?)`

Monitors

Platform-Specific Extensions

Identity & native handles

macOS runtime extensions

Linux runtime extensions

iOS runtime extensions

Android runtime extensions

Events

Disposal