Electron in Practice: Customizing Mac Menus

Preface

Previous articles covered developing an Electron app through to Mac packaging.

Related articles:

Learn Electron in One Article

Electron in Practice: Local Database SQLite

Electron in Practice: Managing Electron Projects with Monorepo

Electron in Practice: Mac Packaging

Electron in Practice: Registering an Apple Developer Account

Electron in Practice: Mac App Signing and Notarization

Electron in Practice: Customizing DMG Installers

This article covers customizing Mac menus.

Default Mac Menu

When developing a Mac app with Electron,

if you don’t customize the Mac menu,

the default looks like this:

Menu

You can customize the Mac menu bar using Electron’s Menu API.

https://www.electronjs.org/zh/docs/latest/api/menu

The core code is as follows, where template is a menu template array:

const menu = Menu.buildFromTemplate(template);
Menu.setApplicationMenu(menu);

Using Built-in Roles

A common approach in menu templates is to use built-in roles.

Electron wraps common menu items and their click actions into roles:

[
  {
    label: 'Edit',
    submenu: [
      { role: 'undo' },
      { role: 'redo' },
      { type: 'separator' },
      { role: 'cut' },
      { role: 'copy' },
      { role: 'paste' },
    ],
  },
];

For example, the copy role above will perform a copy operation when clicked.

Using Custom Menu Items

In addition to built-in roles, you can define custom menu items:

[
  {
    role: 'help',
    submenu: [
      {
        label: 'Learn More',
        click: async () => {
          const { shell } = require('electron');
          await shell.openExternal('https://electronjs.org');
        },
      },
    ],
  },
];

Common Template

Here is a common template based on typical Chinese app menus:

[
  {
    label: 'app',
    submenu: [
      {
        label: 'About',
        role: 'about',
      },
      {
        type: 'separator',
      },
      {
        label: 'Hide',
        role: 'hide',
      },
      {
        label: 'Hide Others',
        role: 'hideOthers',
      },
      {
        type: 'separator',
      },
      {
        label: 'Quit',
        role: 'quit',
      },
    ],
  },
  {
    label: 'Edit',
    submenu: [
      {
        label: 'Undo',
        role: 'undo',
      },
      {
        label: 'Redo',
        role: 'redo',
      },
      {
        type: 'separator',
      },
      {
        label: 'Cut',
        role: 'cut',
      },
      {
        label: 'Copy',
        role: 'copy',
      },
      {
        label: 'Paste',
        role: 'paste',
      },
      {
        label: 'Delete',
        role: 'delete',
      },
      {
        label: 'Select All',
        role: 'selectAll',
      },
    ],
  },
  {
    label: 'Window',
    submenu: [
      {
        label: 'Minimize',
        role: 'minimize',
      },
      {
        label: 'Close',
        role: 'close',
      },
      {
        label: 'Toggle Fullscreen',
        role: 'togglefullscreen',
      },
    ],
  },
  {
    label: 'Debug',
    submenu: [
      {
        label: 'DevTools',
        role: 'toggleDevTools',
      },
    ],
  },
];

Result

qiao-x-menu

A library for working with Electron menus has been created — feel free to use it:

https://code.insistime.com/#/qiao-x-menu

The menu customization above can be simplified to:

import { setApplicationMenu } from 'qiao-x-menu';

setApplicationMenu(menus);