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.

WebviewJS on macOS delegates rendering to the system’s built-in WebKit (WKWebView), so no additional runtime installation is required and your users always get the WebKit version their OS provides. The library wraps Tao’s macOS-specific window extensions to expose native features like transparent titlebars, full-size content views, native window tabs, simple fullscreen mode, and the document-edited indicator — all available as first-class JavaScript APIs.

​
WebKit and System Requirements

macOS 10.15 Catalina or later is required. WebKit is bundled with the OS; your application ships zero renderer code. The currently-loaded WebKit version is returned by getWebviewVersion(): 
import { getWebviewVersion } from '@webviewjs/webview';

console.log(getWebviewVersion()); // e.g. "618.2.12.11.7"

​
Main-Thread Requirement

macOS enforces that all GUI operations happen on the main thread. WebviewJS handles this automatically — but you must not create Application or BrowserWindow from a worker_threads Worker or any async context that migrates execution off the main thread.
Creating windows from a worker_threads Worker will throw or produce undefined behaviour on macOS. Always instantiate Application and BrowserWindow on the main thread.

​
App-Level Menu Bar

On macOS the menu bar spans the top of the entire screen and is owned by the application, not any individual window. Use app.setMenu() to set it: 
app.setMenu({
  items: [
    {
      label: 'App',
      submenu: {
        items: [
          { role: 'about' },
          { role: 'services' },
          { role: 'hide' },
          { role: 'hideothers' },
          { role: 'showall' },
          { role: 'quit' },
        ],
      },
    },
    {
      label: 'Edit',
      submenu: {
        items: [
          { role: 'undo' },
          { role: 'redo' },
          { role: 'cut' },
          { role: 'copy' },
          { role: 'paste' },
          { role: 'selectall' },
        ],
      },
    },
  ],
});

​
Standard macOS Roles

All predefined menu roles work on macOS:
RoleDefault shortcut
hide⌘H
hideothers⌥⌘H
showall—
bringalltofront—
servicesServices submenu
quit⌘Q
about—
On macOS the menu bar is global — win.setMenu() on a per-window basis is silently ignored. Use app.setMenu() exclusively.

​
macOS-Specific Window Options

BrowserWindowOptions exposes a rich set of macOS-only fields that map onto Tao’s WindowBuilderExtMacOS trait: 
const win = app.createBrowserWindow({
  // Allow dragging the window by clicking on its background (traffic-light area excluded)
  macosMovableByWindowBackground: true,

  // Make the titlebar background transparent
  macosTitlebarTransparent: true,

  // Hide the window title text
  macosTitleHidden: true,

  // Hide the entire titlebar (traffic lights and title)
  macosTitlebarHidden: false,

  // Hide the traffic-light buttons while keeping the title
  macosTitlebarButtonsHidden: false,

  // Extend content under the titlebar (needed with transparent titlebar)
  macosFullsizeContentView: true,

  // Force 1× rendering, disable Retina (for pixel-art or legacy content)
  macosDisallowHidpi: false,

  // Control the window drop shadow at creation time
  macosHasShadow: true,

  // Group this window with others in the same tab
  macosTabbingIdentifier: 'my-app-documents',
});

​
Option Reference

OptionTypeDescription
macosMovableByWindowBackgroundbooleanDrag the window by clicking its background
macosTitlebarTransparentbooleanTransparent titlebar background
macosTitleHiddenbooleanHide the title text (traffic lights remain)
macosTitlebarHiddenbooleanHide the full titlebar including buttons
macosTitlebarButtonsHiddenbooleanHide close/minimise/maximise buttons only
macosFullsizeContentViewbooleanExtend content view under the titlebar
macosDisallowHidpibooleanForce 1× scale; disables Retina rendering
macosHasShadowbooleanInitial drop-shadow state
macosTabbingIdentifierstringNative tab group identifier

​
Transparent Windows

Combine transparent, decorations, and a transparent webview background for a fully see-through, frameless window: 
const win = app.createBrowserWindow({
  transparent: true,
  decorations: false,
  macosHasShadow: false,
});

const webview = win.createWebview({ transparent: true });
webview.setBackgroundColor(0, 0, 0, 0); // r, g, b, a — fully transparent
Use macosFullsizeContentView: true together with macosTitlebarTransparent: true so your HTML content extends behind the traffic-light buttons for a seamless look.

​
Simple Fullscreen

macOS has two fullscreen modes. The standard mode (FullscreenType.Borderless) uses the native macOS fullscreen space and slides between Spaces. “Simple fullscreen” is the older mode (pre-10.7 style) that maximises the window within the current desktop without creating a new Space: 
// Enter simple fullscreen (legacy macOS style)
win.setSimpleFullscreen(true);

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

// Exit
win.setSimpleFullscreen(false);

​
Window Shadow

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

// Toggle the shadow at runtime
win.setHasShadow(true);
win.setHasShadow(false);

​
Native Window Tabs

macOS supports grouping multiple windows into a single tabbed window using a tabbing identifier. Windows with the same identifier may be merged into one tab group by the user or programmatically: 
// Set at creation
const win = app.createBrowserWindow({
  macosTabbingIdentifier: 'editor',
});

// Read at runtime
const id = win.tabbingIdentifier(); // "editor"

// Change at runtime
win.setTabbingIdentifier('viewer');

​
Document Edited Indicator

macOS shows a small dot in the close button when a document has unsaved changes. Toggle it with setDocumentEdited(): 
// Mark as edited (dot appears in close button)
win.setDocumentEdited(true);

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

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

​
Fullscreen

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

// Native macOS fullscreen (creates a new Space)
win.setFullscreen(FullscreenType.Borderless);

// Exit fullscreen
win.setFullscreen();

​
Known Limitations

win.setSkipTaskbar(true) does nothing on macOS. To hide your app from the Dock you must set NSApplication.setActivationPolicy to .accessory or .prohibited, which requires an App Sandbox entitlement and is outside the scope of the WebviewJS API.
macOS determines the Dock icon from the app bundle’s Info.plist. Setting a window icon via win.setWindowIcon() has no effect on the Dock tile.
win.setIgnoreCursorEvents(true) is supported via NSWindow.setIgnoresMouseEvents(_:). The window will pass all mouse events through to whatever is behind it.

Build docs developers (and LLMs) love

Get started for freeTalk to us