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.

The Application class is the root of every WebviewJS program. It owns the native OS event loop (powered by Tao), drives the pump that feeds events to all windows, and acts as the single factory for BrowserWindow, WebContext, and TrayIcon instances. You must create exactly one Application per process, then call whenReady() (or run()) before interacting with any window or webview.

​
Constructor

new Application(options?: ApplicationOptions)
​
options
ApplicationOptions
Reserved for future use. Pass null or omit entirely.

​
Methods

​
whenReady(options?)

Returns a Promise that resolves the first time the native event loop emits its resumed() lifecycle callback, indicating the OS is ready to display windows. By default this also starts the event pump via run() so your .then() callback fires as soon as hardware is ready. 
app.whenReady(options?: ApplicationWhenReadyOptions): Promise<void>
​
options
ApplicationWhenReadyOptions
​
returns
Promise<void>
Resolves once the native event loop is ready. Subsequent calls after readiness also resolve asynchronously.
import { Application } from '@webviewjs/webview';

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

const win = app.createBrowserWindow({ title: 'Hello', width: 900, height: 600 });
win.createWebview({ url: 'https://example.com' });
whenReady() is the recommended entry point. It combines the “wait for OS readiness” and “start the loop” steps into a single await.

​
isReady()

Returns true after the native event loop has fired its first resumed() event. 
app.isReady(): boolean
​
returns
boolean
true if the app is ready, false otherwise.

​
run(options?)

Start the event pump. Calls pumpEvents() on a setInterval and returns immediately, leaving the Node.js event loop free to handle I/O, timers, and promises in parallel. 
app.run(options?: ApplicationRunOptions): void
​
options
object

​
exit()

Stop the pump, hide all tracked windows, and mark the application as exited. Subsequent pumpEvents() calls return false. All owned resources (windows, webviews, web contexts, tray icons) are disposed automatically. 
app.exit(): void
After exit(), creating new windows or webviews will throw. Retained wrapper objects report isDisposed() === true.

​
pumpEvents()

Process one batch of OS events without blocking. Returns true while the app is alive, false when the app should stop. Normally called automatically by run(), but you can drive it manually for precise control (e.g., a custom game loop). 
app.pumpEvents(): boolean
​
returns
boolean
true while alive, false when exit() has been called.

​
runSync()

Run the native event loop on the current thread, blocking JavaScript until the application exits. Use run() when the Node.js event loop must remain available for I/O, timers, and promises. 
app.runSync(): void
runSync() blocks the JS thread completely. No Node.js callbacks, promises, or I/O will be processed while it is running.

​
createBrowserWindow(options?)

Create and return a new top-level BrowserWindow. 
app.createBrowserWindow(options?: BrowserWindowOptions): BrowserWindow
​
options
BrowserWindowOptions
See BrowserWindow options for the full options reference.
​
returns
BrowserWindow
A new BrowserWindow instance.

​
createChildBrowserWindow(options?)

Create a child/popup window. The webview inside fills a precise sub-region of the parent rather than the whole window, useful for overlay UIs or panels. 
app.createChildBrowserWindow(options?: BrowserWindowOptions): BrowserWindow
​
options
BrowserWindowOptions
Same shape as createBrowserWindow. The resulting window reports isChild === true.
​
returns
BrowserWindow
A new child BrowserWindow instance.

​
createWebContext(options?)

Create an isolated browser-data context that can be shared across multiple webviews for cookie, cache, and storage sharing — or used in isolation for profile separation. 
app.createWebContext(options?: WebContextOptions): WebContext
​
options
WebContextOptions
​
returns
WebContext
A new WebContext instance. See WebContext reference.
Always create contexts through app.createWebContext() — calling new WebContext() is not supported.

​
createTrayIcon(options)

Create a system tray icon. 
app.createTrayIcon(options: TrayIconOptions): TrayIcon
​
options
TrayIconOptions
required
​
returns
TrayIcon
A new TrayIcon instance.

​
setMenu(options?)

Set the global application menu. Pass null or omit to remove the current menu. 
app.setMenu(options?: MenuOptions): void
​
options
MenuOptions
{ items: MenuItemOptions[] } — see the Menus guide for the full shape.

​
Symbol.dispose

Application implements the TC39 Explicit Resource Management protocol. Use the using declaration to guarantee exit() is called even if an exception is thrown. 
{
  using app = new Application();
  await app.whenReady();
  // … create windows, run app …
} // app.exit() is called automatically here

​
Events

Application extends the standard Node.js EventEmitter. All on, once, off, addListener, removeListener, removeAllListeners, listenerCount, listeners, rawListeners, emit, and eventNames methods are available. Listener-registration and removal methods are chainable.
EventPayloadFired when
window-close-requestedApplicationEventUser clicks the OS close button on a window
application-close-requestedApplicationEventThe last window is closed
custom-menu-clickApplicationEvent (with customMenuEvent)A custom menu item is selected
readyApplicationEventThe native event loop is ready
interface ApplicationEvent {
  event: WebviewApplicationEvent; // numeric enum value
  customMenuEvent?: {
    id: string;
    windowId: number;
  };
}
WebviewApplicationEvent enum values: WindowCloseRequested (0), ApplicationCloseRequested (1), CustomMenuClick (2), Ready (3). 
import { Application } from '@webviewjs/webview';

const app = new Application();

app.on('window-close-requested', (event) => {
  console.log('Window close requested', event);
});

app.on('custom-menu-click', ({ customMenuEvent }) => {
  console.log('Menu item clicked:', customMenuEvent.id, 'on window', customMenuEvent.windowId);
});

app.on('application-close-requested', () => {
  // Exit cleanly when the last window closes.
  app.exit();
});

await app.whenReady();

const win = app.createBrowserWindow({ title: 'Events demo', width: 900, height: 600 });
win.createWebview({ url: 'https://example.com' });

​
Legacy event API

Prefer the EventEmitter on()/once() interface above for new code. The onEvent/bind API is kept for backward compatibility.

​
onEvent(handler) / bind(handler)

Register a callback for all application-level events. Both names are equivalent aliases for the same underlying registration. 
app.onEvent(handler: (event: ApplicationEvent) => void): void
app.bind(handler: (event: ApplicationEvent) => void): void

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

const app = new Application();

app.onEvent((event) => {
  if (event.event === WebviewApplicationEvent.ApplicationCloseRequested) {
    app.exit();
  }
  if (event.event === WebviewApplicationEvent.CustomMenuClick) {
    console.log('Menu item id:', event.customMenuEvent?.id);
  }
});

​
Root-owned disposal

All resources created through an Application are owned by that application. Calling app.exit(), using Symbol.dispose, or letting the application be finalized will dispose every tray icon, webview, window, web context, menu, and callback registered under it. Cleanup is idempotent — calling exit() twice is safe. Retained wrapper objects report isDisposed() === true and reject further method calls after disposal.

Build docs developers (and LLMs) love

Get started for freeTalk to us