Opening and Managing Multiple Windows in WebviewJS

WebviewJS drives all windows from a single event loop pump started by app.run(). Each window is an independent BrowserWindow instance with its own embedded Webview. You can create as many windows as you need before or after calling app.run(), and all of them share the same non-blocking event loop — ordinary Node timers and I/O continue running alongside native window events.

Opening multiple windows

Create each window with app.createBrowserWindow() and attach a webview. All windows start together when the shared event loop runs.

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

const app = new Application();

function createWindow(title, url) {
  const win = app.createBrowserWindow({ title, width: 900, height: 600 });
  const webview = win.createWebview({ url });
  return { win, webview };
}

const docs   = createWindow('Docs',   'https://example.com/docs');
const editor = createWindow('Editor', 'https://example.com/editor');

app.run();

Both windows share the same event loop. There is no need to synchronise them manually.

Tracking windows

Assign a stable string or numeric ID to each window when you create it and store it in a Map. Check the Map before creating a duplicate, and call win.show() to bring an existing window to the foreground instead.

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

const app = new Application();
const windows = new Map(); // id → { win, webview }

function openWindow(id, url) {
  if (windows.has(id)) {
    // Window already exists — bring it to the front
    windows.get(id).win.show();
    return;
  }

  const win = app.createBrowserWindow({ title: id, width: 800, height: 600 });
  const webview = win.createWebview({ url });
  windows.set(id, { win, webview });
}

openWindow('main',     'https://example.com');
openWindow('settings', 'https://example.com/settings');

app.run();

Use app.createChildBrowserWindow() for dialogs, palettes, and tool panels that should be positioned relative to a parent window. Child windows behave like independent windows but share the parent’s native context.

const app = new Application();
const main = app.createBrowserWindow({ title: 'Main Window', width: 1000, height: 700 });
main.createWebview({ url: 'app://localhost/index.html' });

// Open a Settings popup
const settings = app.createChildBrowserWindow({
  title:  'Settings',
  width:  400,
  height: 300,
});
settings.createWebview({ url: 'app://localhost/settings.html' });

app.run();

Show and hide instead of destroy

When the user clicks the OS close button on a window, the WebviewJS runtime hides the window rather than destroying it. The native resources remain allocated, and you can show the window again at any time without re-creating it.

// Toggle visibility based on current state
function toggleWindow(win) {
  win.setVisible(!win.isVisible());
}

// Or use the explicit helpers
win.show();
win.hide();

This pattern is especially useful for persistent tool windows or settings panels that users open and close frequently.

Window lifecycle events

Listen for lifecycle events on the Application instance to respond to window and application close requests.

app.on('window-close-requested', () => {
  // One window has been hidden by the runtime.
  // Individual window references remain valid — call win.show() to restore.
  console.log('A window was hidden.');
});

app.on('application-close-requested', () => {
  // Every tracked window is now hidden.
  // This is the right place to call app.exit() for a clean shutdown.
  console.log('All windows hidden — exiting.');
  app.exit();
});

window-close-requested fires each time a single window is hidden. application-close-requested fires once all windows are hidden. If you do not call app.exit() inside application-close-requested, the application continues running (useful for tray-only apps).

Disposal

Call win.dispose() to immediately release a window and its webview before calling app.exit(). Disposal is idempotent — calling it more than once is safe.

// Explicit disposal
win.dispose();

// Or use the using-declaration with Symbol.dispose (Node.js >= 18 / ES2022)
{
  using win = app.createBrowserWindow({ title: 'Temporary' });
  win.createWebview({ html: '<p>Hello</p>' });
  // win.dispose() is called automatically when the block exits
}

app.exit() disposes all root-owned windows and webviews in shutdown order. After disposal, win.isDisposed() returns true and further method calls throw a disposed error.

Keep a strong JavaScript reference to each BrowserWindow and Webview for as long as you need to call their methods or retain their event listeners. Dropping the last reference allows the garbage collector to run finalizers, which may trigger unexpected disposal.

Menus — per-window and global menu bars
IPC Messaging — communicating between windows and Node.js
BrowserWindow API reference — full method signatures for show, hide, setVisible, dispose, and window options

Get Started

Guides

Platform Notes

Opening and Managing Multiple Windows in WebviewJS

Opening multiple windows

Tracking windows

Show and hide instead of destroy

Window lifecycle events

Disposal

​Opening multiple windows

​Tracking windows

​Child (popup) windows

​Show and hide instead of destroy

​Window lifecycle events

​Disposal

​Related pages

Opening multiple windows

Tracking windows

Child (popup) windows

Show and hide instead of destroy

Window lifecycle events

Disposal

Related pages