Menu API — Native Menu Bars, Roles, and Shortcuts

WebviewJS uses muda to render native menu bars on supported desktop platforms. Menus can be global (app-level, shared across windows) or per-window on Windows and Linux. macOS has one application-level menu bar. Custom menu items with an id emit custom-menu-click to your Node.js process.

Call app.setMenu(MenuOptions) to configure the global menu. Set it before creating windows on Windows and Linux, where the menu is attached during window construction. On macOS it configures the application-level menu and can be called at any time.

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

const app = new Application();

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

const win = app.createBrowserWindow({ title: 'My App' });
win.createWebview({ url: 'https://example.com' });

app.run();

Calling setMenu() again replaces the current global menu definition. On Windows and Linux, the replacement is not reattached to existing windows; new windows use it. Configure the global menu before creating windows when all windows should receive the same menu. On macOS the application-level menu is updated. Pass null to remove the non-macOS global menu; macOS restores its default application menu.

// Remove the menu bar
app.setMenu(null);

Listen for the custom-menu-click application event to respond to clicks on any menu item that has an id. The payload contains a customMenuEvent object with the clicked item’s identifier. Its windowId field is currently emitted as 0 and is not a reliable originating-window identifier.

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

  switch (customMenuEvent.id) {
    case 'file-new':
      createNewDocument();
      break;
    case 'file-open': {
      const paths = win.openFileDialog({ title: 'Open file' });
      if (paths.length) openFile(paths[0]);
      break;
    }
    case 'file-save':
      saveDocument();
      break;
  }
});

Field	Type	Description
`id`	`string`	The `id` set on the `MenuItemOptions` that was clicked.
`windowId`	`number`	Currently `0`; do not use it to identify the originating window.

Items that use a role (e.g. copy, quit) are handled natively and do not emit custom-menu-click.

Updating menus at runtime

Replace the global menu by calling app.setMenu() again with a new MenuOptions object. On Windows and Linux, the replacement is not reattached to existing windows; later-created windows use it. On macOS the application-level menu updates immediately.

// Disable the Save item while a save is in progress
function setSaveEnabled(enabled) {
  app.setMenu({
    items: [
      {
        label: 'File',
        submenu: {
          items: [
            { id: 'file-save', label: 'Save', accelerator: 'CmdOrCtrl+S', enabled },
            { role: 'quit' },
          ],
        },
      },
    ],
  });
}

To remove the menu bar entirely, pass null:

app.setMenu(null);

Per-window menus

On Windows and Linux, pass menu: MenuOptions when creating a window to attach a menu that overrides the global menu for that specific window. There is no win.setMenu() method. Windows without a per-window menu use the global menu attached when they were created; changing the global menu later does not reattach it. On macOS, the menu bar is application-level; use app.setMenu().

const editorWin = app.createBrowserWindow({
  title: 'Editor',
  menu: {
    items: [
      {
        label: 'Format',
        submenu: {
          items: [
            { id: 'fmt-bold',   label: 'Bold',   accelerator: 'CmdOrCtrl+B' },
            { id: 'fmt-italic', label: 'Italic', accelerator: 'CmdOrCtrl+I' },
          ],
        },
      },
    ],
  },
});

On Windows and Linux, if you use only a per-window menu, initialize menu event delivery before pumping the application by setting a non-null global menu with app.setMenu(...) or creating a tray icon. The current application loop starts draining menu events when one of those resources initializes its menu-event receiver.

Per-window menu clicks also fire custom-menu-click on app. The current customMenuEvent.windowId value is 0, so route clicks using your own window state when you need per-window behavior.

MenuItemOptions

Every entry in a submenu.items array is a MenuItemOptions object.

interface MenuItemOptions {
  id?:          string;
  label?:       string;
  enabled?:     boolean;
  accelerator?: string;
  role?:        string;
  submenu?:     MenuOptions;
}

Field	Type	Default	Description
`id`	`string`	—	Unique identifier emitted in `custom-menu-click` events. Required for custom items you want to handle in code.
`label`	`string`	—	Display text shown in the menu. Not required when using `role: 'separator'`.
`enabled`	`boolean`	`true`	When `false` the item is shown but grayed out and unclickable.
`accelerator`	`string`	—	Keyboard shortcut string (see Keyboard accelerators). Displayed next to the label.
`role`	`string`	—	Maps to a predefined native action (see Predefined roles). Overrides `label` and `id`.
`submenu`	`MenuOptions`	—	Nested `MenuOptions` object. When present the item becomes a submenu parent and `id`/`accelerator` are ignored.

Predefined roles

Roles map menu items to native platform actions and are automatically localised into the system language. You do not need to supply label, id, or accelerator for role items.

Availability follows Muda’s native backend. On Linux, the GTK backend supports separators, copy/cut/paste/select-all, and About items. The About item can be rendered, but WebviewJS does not provide About metadata and the default action is backend-dependent. The GTK backend omits the other predefined roles such as undo, minimize, fullscreen, close, and quit. Menus are disabled on Android, and the published FreeBSD target is a GUI stub.

Role	Action	Platform availability
`copy`	Copy selection to clipboard	Windows / macOS / Linux
`paste`	Paste from clipboard	Windows / macOS / Linux
`cut`	Cut selection to clipboard	Windows / macOS / Linux
`undo`	Undo last action	Windows / macOS
`redo`	Redo last undone action	Windows / macOS
`selectall` / `select-all`	Select all content	Windows / macOS / Linux
`separator` / `-`	Horizontal separator line	Windows / macOS / Linux
`minimize`	Minimise the window	Windows / macOS
`maximize`	Maximise the window	Windows / macOS
`fullscreen`	Toggle fullscreen mode	macOS only
`close` / `closewindow` / `close-window`	Close the current window	Windows / macOS
`quit`	Quit the application	Windows / macOS
`about`	Native About item; default action is functional on macOS	macOS; may render elsewhere
`hide`	Hide the application	macOS only
`hideothers` / `hide-others`	Hide all other applications	macOS only
`showall` / `show-all`	Show all applications	macOS only
`services`	Insert the Services submenu	macOS only
`bringalltofront` / `bring-all-to-front`	Bring all windows to the front	macOS only

Keyboard accelerators

An accelerator string defines a keyboard shortcut displayed next to the menu label. The format is a +-separated list of modifiers followed by a key name.

Token	Meaning
`CmdOrCtrl`	`Cmd` on macOS, `Ctrl` on Windows and Linux
`Ctrl`	`Ctrl` on all platforms
`Alt`	`Alt` / `Option`
`Shift`	`Shift`
`Super`	`Win` key on Windows, `Super` on Linux

Examples

Accelerator string	Result on macOS	Result on Windows / Linux
`CmdOrCtrl+S`	`⌘S`	`Ctrl+S`
`CmdOrCtrl+Shift+S`	`⇧⌘S`	`Ctrl+Shift+S`
`Alt+F4`	`⌥F4`	`Alt+F4`
`Shift+CmdOrCtrl+Z`	`⇧⌘Z`	`Ctrl+Shift+Z`
`F5`	`F5`	`F5`

Nested submenus

Set the submenu field on any menu item to create a hierarchical menu structure. The source supports recursive nested submenus; the native platform may impose its own rendering limits.

app.setMenu({
  items: [
    {
      label: 'View',
      submenu: {
        items: [
          { id: 'reload',   label: 'Reload',          accelerator: 'CmdOrCtrl+R' },
          { id: 'devtools', label: 'Developer Tools',  accelerator: 'F12' },
          { role: 'separator' },
          {
            label: 'Zoom',          // parent item — no id or accelerator
            submenu: {
              items: [
                { id: 'zoom-in',    label: 'Zoom In',    accelerator: 'CmdOrCtrl+=' },
                { id: 'zoom-out',   label: 'Zoom Out',   accelerator: 'CmdOrCtrl+-' },
                { id: 'zoom-reset', label: 'Actual Size', accelerator: 'CmdOrCtrl+0' },
              ],
            },
          },
        ],
      },
    },
  ],
});

When an item has a submenu, the id and accelerator fields on that parent item are ignored — only label and enabled apply.

Platform differences

Platform	Behaviour
Windows	Each window has its own menu bar attached inside the title-bar area.
macOS	A single app-level menu bar is displayed at the top of the screen; it is shared globally.
Linux	Per-window GTK menu bar. Requires WebKitGTK 4.1 (`libwebkit2gtk-4.1-dev`). `custom-menu-click` events fire normally. Display depends on the desktop environment — test on your target configurations.

The menu system is disabled on Android. The published FreeBSD target is a GUI stub.

Core

UI & System

Types

Menu API — Native Menu Bars, Roles, and Shortcuts

Setting a global menu

Handling menu clicks

Updating menus at runtime

Per-window menus

MenuItemOptions

Predefined roles

Keyboard accelerators

Nested submenus

Platform differences

​Setting a global menu

​Handling menu clicks

​Updating menus at runtime

​Per-window menus

​MenuItemOptions

​Predefined roles

​Keyboard accelerators

​Nested submenus

​Platform differences

Setting a global menu

Handling menu clicks

Updating menus at runtime

Per-window menus

MenuItemOptions

Predefined roles

Keyboard accelerators

Nested submenus

Platform differences