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();

Child-marked windows

Use app.createChildBrowserWindow() for windows that should be marked as child windows. The method does not accept a parent window and does not establish a native parent/owner relationship. Child windows are otherwise independent BrowserWindow instances.

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 window
const settings = app.createChildBrowserWindow({
  title:  'Settings',
  width:  400,
  height: 300,
});
settings.createWebview({ url: 'app://localhost/settings.html' });

app.run();

If you need a webview to occupy a specific rectangle inside its host window, create it with child: true and provide x, y, width, and height.

Show and hide instead of destroy

When the OS delivers a close request, WebviewJS hides the native window and removes it from the application’s tracked window set. A close request for the last tracked window also shuts the application down and disposes its resources. Use win.hide() when you want a window to remain part of the live application and be shown again later.

// 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', () => {
  console.log('A window close was requested.');
});

app.on('application-close-requested', () => {
  // The runtime shuts down after this event. app.exit() is safe but optional.
  console.log('The OS close request removed the last tracked window.');
  app.exit();
});

window-close-requested fires for each OS close request. When that request removes the last tracked window, application-close-requested fires and shutdown follows immediately. For a tray-only workflow, hide the window rather than allowing the last tracked window to receive an OS close request.

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 24+)
{
  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 JavaScript reference to each BrowserWindow and Webview for as long as you need to call their methods or retain their event listeners. The application owns the native resources; garbage-collecting a wrapper does not itself dispose the native object.

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

Child-marked windows

Show and hide instead of destroy

Window lifecycle events

Disposal

​Opening multiple windows

​Tracking windows

​Child-marked windows

​Show and hide instead of destroy

​Window lifecycle events

​Disposal

​Related pages

Opening multiple windows

Tracking windows

Child-marked windows

Show and hide instead of destroy

Window lifecycle events

Disposal

Related pages