WebviewJS on macOS: WebKit, Titlebar and Native Tab APIs

WebviewJS on macOS uses the built-in WebKit engine (WKWebView) — the same engine that powers Safari. No additional runtime installation is needed; WebKit is part of the operating system. macOS 10.15 Catalina or later is required.

Supported architectures

Target triple	Architecture	CI
`x86_64-apple-darwin`	x64 (Intel)	✅
`aarch64-apple-darwin`	arm64 (Apple Silicon)	✅

Universal binaries (fat binaries targeting both slices) can be produced during the build step. See the Building Executables guide for details.

Threading requirement

macOS enforces that all GUI operations run on the main thread. Do not create Application or BrowserWindow from a worker_threads Worker or any async context that migrates the call off the main thread. WebviewJS handles main-thread dispatch internally, but the initial construction calls must originate from the main thread.

macOS-specific creation options

Pass these fields in BrowserWindowOptions when calling app.createBrowserWindow(). They are silently ignored on other platforms.

Option	Type	Description
`macosMovableByWindowBackground`	`boolean`	Allow the user to drag the window by clicking anywhere on the background (not just the title bar).
`macosTitlebarTransparent`	`boolean`	Render the title bar with a transparent background, letting window content show through.
`macosTitleHidden`	`boolean`	Hide the window title text while keeping the title bar visible.
`macosTitlebarHidden`	`boolean`	Remove the title bar entirely, producing a fully content-filled window.
`macosTitlebarButtonsHidden`	`boolean`	Hide the traffic-light buttons (close, minimize, zoom) without removing the title bar.
`macosFullsizeContentView`	`boolean`	Extend the content view behind the title bar so your UI fills the full window height.
`macosDisallowHidpi`	`boolean`	Disable HiDPI/Retina mode and render at 1× pixel density.
`macosHasShadow`	`boolean`	Control whether the window casts a drop shadow. Defaults to `true`.
`macosTabbingIdentifier`	`string`	Group windows into a native macOS tab bar when they share the same identifier string.

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

const app = new Application();

app.whenReady().then(() => {
  const win = app.createBrowserWindow({
    title: 'My App',
    macosTitlebarTransparent: true,
    macosFullsizeContentView: true,
    macosTitlebarButtonsHidden: false,
    macosHasShadow: true,
    macosTabbingIdentifier: 'com.myapp.main',
  });

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

macOS runtime methods

Simple fullscreen (pre-Lion style)

macOS introduced a slide-in fullscreen mode in Lion (10.7). The older “simple” fullscreen expands the window to fill the screen without a separate Space:

// Check current state
const isSimple = win.simpleFullscreen(); // boolean

// Enter or exit simple fullscreen
win.setSimpleFullscreen(true);
win.setSimpleFullscreen(false);

Use win.setFullscreen(FullscreenType.Borderless) for the modern macOS fullscreen Space instead.

Window shadow

// Read the current shadow state
const hasShadow = win.hasShadow(); // boolean

// Enable or disable the drop shadow
win.setHasShadow(true);
win.setHasShadow(false);

Native window tabs

macOS can merge multiple windows of the same app into a tab bar when they share a tabbing identifier:

// Assign a tabbing identifier at runtime (also available as a creation option)
win.setTabbingIdentifier('com.myapp.editor');

// Read the current identifier
const id = win.tabbingIdentifier(); // string

Document edited state

Set the document-edited flag to display the standard macOS dot in the close button, signalling unsaved changes:

// Check the state
const edited = win.isDocumentEdited(); // boolean

// Mark as edited (shows dot in close button)
win.setDocumentEdited(true);

// Clear after saving
win.setDocumentEdited(false);

On macOS the menu bar is a single, application-level bar that spans the top of the screen — it belongs to the app, not to any individual window. Set it via app.setMenu():

app.setMenu({
  items: [
    {
      label: 'File',
      submenu: {
        items: [
          { id: 'new',  label: 'New',  accelerator: 'CmdOrCtrl+N' },
          { id: 'open', label: 'Open', accelerator: 'CmdOrCtrl+O' },
          { role: 'separator' },
          { role: 'quit' },
        ],
      },
    },
    {
      label: 'Edit',
      submenu: {
        items: [
          { role: 'copy' },
          { role: 'paste' },
          { role: 'cut' },
          { role: 'selectall' },
        ],
      },
    },
  ],
});

The application-level menu is ready as soon as app.setMenu() returns. All predefined roles work on macOS. The following roles are macOS-exclusive:

Role	Keyboard shortcut	Description
`hide`	`⌘H`	Hide the front application.
`hideothers`	`⌥⌘H`	Hide all other applications.
`showall`	—	Unhide all applications.
`services`	—	Insert the system Services submenu.
`bringalltofront`	—	Bring all app windows to the front.
`about`	—	Show the standard About panel.

{
  label: 'MyApp',
  submenu: {
    items: [
      { role: 'about' },
      { role: 'separator' },
      { role: 'services' },
      { role: 'separator' },
      { role: 'hide' },
      { role: 'hideothers' },
      { role: 'showall' },
      { role: 'separator' },
      { role: 'quit' },
    ],
  },
}

System tray

WebviewJS supports macOS template icons — monochrome images that the system automatically adapts to the current Dark or Light menu bar appearance:

const tray = app.createTrayIcon({
  id: 'main',
  icon: { data: monochromeRgba, width: 22, height: 22 },
  tooltip: 'My App',
});

// Mark the icon as a template so macOS inverts it automatically
tray.setIconAsTemplate(true);

Template icons should be black (or black with alpha). The system handles colour inversion for Dark Mode — you do not need to supply separate assets.

Get Started

Guides

Platform Notes

WebviewJS on macOS: WebKit, Titlebar and Native Tab APIs

Supported architectures

Threading requirement

macOS-specific creation options

macOS runtime methods

Simple fullscreen (pre-Lion style)

Window shadow

Native window tabs

Document edited state

Menu bar

macOS-specific menu roles

System tray

​Supported architectures

​Threading requirement

​macOS-specific creation options

​macOS runtime methods

​Simple fullscreen (pre-Lion style)

​Window shadow

​Native window tabs

​Document edited state

​Menu bar

​macOS-specific menu roles

​System tray

Supported architectures

Threading requirement

macOS-specific creation options

macOS runtime methods

Simple fullscreen (pre-Lion style)

Window shadow

Native window tabs

Document edited state

Menu bar

macOS-specific menu roles

System tray