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 or after creating windows. The menu applies to all windows that do not have a per-window override.

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 and the windowId of the window that was frontmost when the item was activated.

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 entire menu tree at any time by calling app.setMenu() again with a new item list. Pass null to remove the menu bar entirely.

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

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

Per-window menus

Call win.setMenu() to assign a menu that applies only to a specific window. This overrides the global menu for that window. Clicks still emit custom-menu-click on the application.

const win = app.createBrowserWindow({ title: 'Editor' });

win.setMenu({
  items: [
    {
      label: 'Editor',
      submenu: {
        items: [
          { id: 'editor-prefs', label: 'Preferences' },
        ],
      },
    },
  ],
});

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.

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)

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	Most roles supported	All roles supported	Most roles supported
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. Both app.setMenu() and win.setMenu() work, and custom-menu-click events fire as expected. 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