Native Application Menus for Your WebviewJS Desktop App

WebviewJS exposes a cross-platform native menu system powered by muda. You define a tree of menu items — labels, roles, accelerators, and submenus — and the OS renders it natively. On macOS the menu bar lives at the top of the screen and belongs to the application. On Windows each window has its own menu bar embedded in the title bar. On Linux a per-window GTK menu bar is attached through Tao’s GTK integration; custom-menu-click events fire on all three platforms. See Platform differences for details.

Call app.setMenu(options) before creating windows when targeting Windows or Linux. Those platforms attach the global menu during window construction, so a later change does not reattach the replacement to existing windows. On macOS, app.setMenu() updates the application-level menu. A per-window menu overrides the global menu on Windows and Linux.

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

const app = new Application();

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: 'undo' },
          { role: 'redo' },
          { role: 'separator' },
          { role: 'cut' },
          { role: 'copy' },
          { role: 'paste' },
        ],
      },
    },
  ],
});

const win = app.createBrowserWindow({ title: 'My App' });
const webview = win.createWebview({ url: 'app://localhost/index.html' });

app.run();

Listen for custom-menu-click on the Application instance. The event payload contains a customMenuEvent object with the id you assigned to the menu item. The current native implementation emits windowId: 0, so do not use that field to identify the originating window.

app.on('custom-menu-click', ({ customMenuEvent }) => {
  switch (customMenuEvent.id) {
    case 'new':
      createNewWindow();
      break;
    case 'open':
      openFilePicker();
      break;
    case 'save':
      saveCurrentDocument();
      break;
    default:
      console.log('Unhandled menu item:', customMenuEvent.id);
  }
});

Only items with an id property emit this event. Role-based items such as copy and paste are handled natively by the OS and do not emit custom-menu-click.

Updating menus at runtime

Replace the global menu definition by calling app.setMenu() again with a new item list. On Windows and Linux, the new definition is used by windows created after the call; it is not reattached to existing windows. On macOS the application-level menu updates immediately. Pass null to remove the global menu on Windows/Linux; macOS restores its default application menu.

// Replace the whole menu
app.setMenu({ items: updatedItems });

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

Per-window menus

On Windows and Linux, pass menu in the BrowserWindowOptions when creating a window to assign a menu that applies only to that window. This overrides the global menu for that window. Clicks still emit custom-menu-click on the application. macOS has one application-level menu bar, so use app.setMenu() there instead of relying on per-window menus.

const win = app.createBrowserWindow({
  title: 'Editor',
  menu: {
    items: [
      {
        label: 'Editor',
        submenu: {
          items: [
            { id: 'editor-prefs', label: 'Preferences' },
          ],
        },
      },
    ],
  },
});

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.

Keyboard accelerators

Specify accelerators with the accelerator property on any custom menu item. Use the following cross-platform modifier tokens:

Accelerator string	Result
`CmdOrCtrl+S`	`Cmd+S` on macOS, `Ctrl+S` on Windows/Linux
`Alt+F4`	`Alt+F4` (literal)
`Shift+CmdOrCtrl+Z`	Redo shortcut, cross-platform
`F5`	Function key `F5`
`F11`	Function key `F11`

{ id: 'save', label: 'Save', accelerator: 'CmdOrCtrl+S' }
{ id: 'redo', label: 'Redo', accelerator: 'Shift+CmdOrCtrl+Z' }
{ id: 'reload', label: 'Reload', accelerator: 'F5' }

Predefined roles

Use role instead of id + label to get OS-native behavior without writing click handlers. Role items are rendered and wired by the platform when that backend supports them.

Role	Description
`separator` / `-`	Horizontal divider line
`copy`	Copy selection to clipboard
`paste`	Paste from clipboard
`cut`	Cut selection to clipboard
`undo`	Undo last action
`redo`	Redo last undone action
`selectall` / `select-all`	Select all text
`minimize`	Minimize the window
`maximize`	Maximize the window
`fullscreen`	Toggle full-screen mode
`close` / `closewindow` / `close-window`	Close the current window
`quit`	Quit the application
`about`	Show the platform About dialog (macOS)
`hide`	Hide the application (macOS)
`hideothers` / `hide-others`	Hide all other applications (macOS)
`showall` / `show-all`	Show all hidden applications (macOS)
`services`	Services submenu (macOS)
`bringalltofront` / `bring-all-to-front`	Bring all windows to front (macOS)

Linux uses Muda’s GTK backend. It 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. Unsupported predefined roles such as undo, minimize, fullscreen, close, and quit are omitted from the GTK menu.

Nested submenus

Nest a submenu inside any top-level or secondary menu item to create hierarchical menus.

{
  label: 'View',
  submenu: {
    items: [
      {
        label: 'Zoom',
        submenu: {
          items: [
            { id: 'zoom-in',    label: 'Zoom In',  accelerator: 'CmdOrCtrl+=' },
            { id: 'zoom-out',   label: 'Zoom Out', accelerator: 'CmdOrCtrl+-' },
            { id: 'zoom-reset', label: 'Reset',    accelerator: 'CmdOrCtrl+0' },
          ],
        },
      },
      { role: 'fullscreen' },
    ],
  },
}

Platform differences

Feature	Windows	macOS	Linux
Menu bar location	Per-window, inside the title bar	App-level, top of screen	Per-window GTK menu bar
Predefined roles	Muda desktop actions	Muda desktop actions	Edit/separator/About roles only
Keyboard accelerators	Yes	Yes	Yes
`custom-menu-click` events	Yes	Yes	Yes

On Linux, WebviewJS uses Muda’s GTK integration to attach a per-window menu bar, and custom-menu-click events fire for custom items. Configure the global menu before creating the window, or pass a menu option when creating the window. The visual appearance is determined by the GTK theme of the desktop environment.

Multiple Windows — per-window menus and window lifecycle
Application API reference — setMenu, on('custom-menu-click'), and application events

Get Started

Guides

Platform Notes

Native Application Menus for Your WebviewJS Desktop App

Setting a global menu

Handling menu clicks

Updating menus at runtime

Per-window menus

Keyboard accelerators

Predefined roles

Nested submenus

Platform differences

​Setting a global menu

​Handling menu clicks

​Updating menus at runtime

​Per-window menus

​Keyboard accelerators

​Predefined roles

​Nested submenus

​Platform differences

​Related pages

Setting a global menu

Handling menu clicks

Updating menus at runtime

Per-window menus

Keyboard accelerators

Predefined roles

Nested submenus

Platform differences

Related pages