Legend SparkExperimental โ€” not for production

Menus and shortcuts

Owned native menus, portable accelerators, command routing, and tray items.

Create menus with typed items and stable IDs. Each surface supports the item types listed below.

Application menus

import { createMenu } from '@legendapp/spark/menus';

const menu = await createMenu({
  id: 'editor',
  items: [{
    type: 'submenu', id: 'file', label: 'File', target: { menu: 'file' },
    items: [{ type: 'action', id: 'open', label: 'Open...', shortcut: 'CmdOrCtrl+O' }],
  }],
  onAction: event => { console.log(event.itemId); },
});
await menu.update({ items: [] });
await menu.remove();

Top-level items are submenus. Contributions merge by IDs, never translated labels. Later owners take precedence; removal restores earlier contributions/native items. Updates replace the owner's contribution. Native publication is acknowledged before create/update resolves. Failed publication retains the previous state; failed removal retains retryable ownership.

Targets bind native root menus, IDs, or macOS semantic roles. Role items dispatch through native responders; ordinary actions targeting roles dispatch to JavaScript. useMenu owns the same lifetime and exposes loading/ready/error state plus cleanup-error callbacks. Keep unchanged item structure stable; callback changes do not require republishing.

Checked items

Use type: 'checkbox' with a boolean checked for selectable state. The shared contract also defines radio, but the surfaces below reject it with E_UNSUPPORTED_OPTION; /menus excludes it from its exported MenuItem type.

Surface support

SurfaceSupported item shapesLimits
App menuRecursive actions, checkboxes, separators, submenus; macOS rolesWindows role/icon requests reject
Context menuFlat actions, checkboxes, separatorsNo submenus, roles, icons, shortcuts, or sliders
Tray menuActions, checkboxes, separators, recursive submenusNo roles, icons, shortcuts, or sliders
macOS toolbar popupActions, checkboxes, separators, numeric slidersNo submenus, roles, or shortcuts
macOS DockRecursive actions, checkboxes, separators, submenusRestricted presentation/targeting fields
Windows taskbarFlat actions and checkboxesDisabled entries omitted; restricted fields

showContextMenu({ windowId, position, items }) requires an explicit owner. Position is logical top-left content coordinates, rather than display/outer-frame coordinates. Cancellation returns { canceled: true }; selection returns { canceled: false, itemId }. A concurrent popup rejects E_BUSY.

createTray returns a handle with update and async remove. Images distinguish SF Symbol names from local files; symbol images are macOS-specific. Dock/taskbar menu registrations live in /system and have separate native availability.

Shortcuts

Set an item's shortcut, such as CmdOrCtrl+O, to show and register its accelerator. Use Keyboard shortcuts for local/global registrations, named commands, customizable bindings, and raw key events.

See menu details for targeting and ownership.