Skip to content

docs: preview menu tutorial #818

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

docs: preview menu tutorial #818

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e21fd3c
docs: preview menu tutorial
erickzhao May 26, 2025
21d3406
add new docs to sidebars.js
erickzhao May 26, 2025
3d47f4b
Merge branch 'main' into docs/menu-tutorial-preview
erickzhao May 27, 2025
084760e
rebase upstream
erickzhao May 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/latest/.sha
View file
Open in desktop

This file was deleted.

11 changes: 5 additions & 6 deletions docs/latest/api/dock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,8 @@ hide_title: false
Process: [Main](../glossary.md#main-process)<br />
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._

The following example shows how to bounce your icon on the dock.

```js
const { app } = require('electron')
app.dock?.bounce()
```
> [!TIP]
> See also: [A detailed guide about how to implement Dock menus](../tutorial/macos-dock.md).

### Instance Methods

Expand Down Expand Up @@ -56,6 +52,9 @@ Bounces the Downloads stack if the filePath is inside the Downloads folder.

Sets the string to be displayed in the dock’s badging area.

> [!IMPORTANT]
> You need to ensure that your application has the permission to display notifications for this method to work.

#### `dock.getBadge()` _macOS_

Returns `string` - The badge string of the dock.
Expand Down
11 changes: 7 additions & 4 deletions docs/latest/api/global-shortcut.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,13 +53,16 @@ app.on('will-quit', () => {
})
```

> [!TIP]
> See also: [A detailed guide on Keyboard Shortcuts](../tutorial/keyboard-shortcuts.md).

## Methods

The `globalShortcut` module has the following methods:

### `globalShortcut.register(accelerator, callback)`

* `accelerator` [Accelerator](accelerator.md)
* `accelerator` string - An [accelerator](../tutorial/keyboard-shortcuts.md#accelerators) shortcut.
* `callback` Function

Returns `boolean` - Whether or not the shortcut was registered successfully.
Expand All @@ -81,7 +84,7 @@ the app has been authorized as a [trusted accessibility client](https://develope

### `globalShortcut.registerAll(accelerators, callback)`

* `accelerators` [Accelerator](accelerator.md)[] - an array of [Accelerator](accelerator.md)s.
* `accelerators` string[] - An array of [accelerator](../tutorial/keyboard-shortcuts.md#accelerators) shortcuts.
* `callback` Function

Registers a global shortcut of all `accelerator` items in `accelerators`. The `callback` is called when any of the registered shortcuts are pressed by the user.
Expand All @@ -100,7 +103,7 @@ the app has been authorized as a [trusted accessibility client](https://develope

### `globalShortcut.isRegistered(accelerator)`

* `accelerator` [Accelerator](accelerator.md)
* `accelerator` string - An [accelerator](../tutorial/keyboard-shortcuts.md#accelerators) shortcut.

Returns `boolean` - Whether this application has registered `accelerator`.

Expand All @@ -110,7 +113,7 @@ don't want applications to fight for global shortcuts.

### `globalShortcut.unregister(accelerator)`

* `accelerator` [Accelerator](accelerator.md)
* `accelerator` string - An [accelerator](../tutorial/keyboard-shortcuts.md#accelerators) shortcut.

Unregisters the global shortcut of `accelerator`.

Expand Down
102 changes: 17 additions & 85 deletions docs/latest/api/menu-item.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,15 @@ See [`Menu`](menu.md) for examples.
* `window` [BaseWindow](base-window.md) | undefined - This will not be defined if no window is open.
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `role` string (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `toggleSpellChecker`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `showSubstitutions`, `toggleSmartQuotes`, `toggleSmartDashes`, `toggleTextReplacement`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `shareMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `showAllTabs`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
`click` property will be ignored. See [roles](#roles).
* `type` string (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
`radio`.
`click` property will be ignored. See [roles](../tutorial/menus.md#roles).
* `type` string (optional)
* `normal`
* `separator`
* `submenu`
* `checkbox`
* `radio`
* `header` - Only available on macOS 14 and up.
* `palette` - Only available on macOS 14 and up.
* `label` string (optional)
* `sublabel` string (optional) _macOS_ - Available in macOS >= 14.4
* `toolTip` string (optional) _macOS_ - Hover text for this menu item.
Expand Down Expand Up @@ -61,88 +67,13 @@ See [`Menu`](menu.md) for examples.
> [!NOTE]
> `acceleratorWorksWhenHidden` is specified as being macOS-only because accelerators always work when items are hidden on Windows and Linux. The option is exposed to users to give them the option to turn it off, as this is possible in native macOS development.

### Roles

Roles allow menu items to have predefined behaviors.

It is best to specify `role` for any menu item that matches a standard role,
rather than trying to manually implement the behavior in a `click` function.
The built-in `role` behavior will give the best native experience.

The `label` and `accelerator` values are optional when using a `role` and will
default to appropriate values for each platform.

Every menu item must have either a `role`, `label`, or in the case of a separator
a `type`.

The `role` property can have following values:

* `undo`
* `about` - Trigger a native about panel (custom message box on Window, which does not provide its own).
* `redo`
* `cut`
* `copy`
* `paste`
* `pasteAndMatchStyle`
* `selectAll`
* `delete`
* `minimize` - Minimize current window.
* `close` - Close current window.
* `quit` - Quit the application.
* `reload` - Reload the current window.
* `forceReload` - Reload the current window ignoring the cache.
* `toggleDevTools` - Toggle developer tools in the current window.
* `togglefullscreen` - Toggle full screen mode on the current window.
* `resetZoom` - Reset the focused page's zoom level to the original size.
* `zoomIn` - Zoom in the focused page by 10%.
* `zoomOut` - Zoom out the focused page by 10%.
* `toggleSpellChecker` - Enable/disable builtin spell checker.
* `fileMenu` - Whole default "File" menu (Close / Quit)
* `editMenu` - Whole default "Edit" menu (Undo, Copy, etc.).
* `viewMenu` - Whole default "View" menu (Reload, Toggle Developer Tools, etc.)
* `windowMenu` - Whole default "Window" menu (Minimize, Zoom, etc.).

The following additional roles are available on _macOS_:

* `appMenu` - Whole default "App" menu (About, Services, etc.)
* `hide` - Map to the `hide` action.
* `hideOthers` - Map to the `hideOtherApplications` action.
* `unhide` - Map to the `unhideAllApplications` action.
* `showSubstitutions` - Map to the `orderFrontSubstitutionsPanel` action.
* `toggleSmartQuotes` - Map to the `toggleAutomaticQuoteSubstitution` action.
* `toggleSmartDashes` - Map to the `toggleAutomaticDashSubstitution` action.
* `toggleTextReplacement` - Map to the `toggleAutomaticTextReplacement` action.
* `startSpeaking` - Map to the `startSpeaking` action.
* `stopSpeaking` - Map to the `stopSpeaking` action.
* `front` - Map to the `arrangeInFront` action.
* `zoom` - Map to the `performZoom` action.
* `toggleTabBar` - Map to the `toggleTabBar` action.
* `selectNextTab` - Map to the `selectNextTab` action.
* `selectPreviousTab` - Map to the `selectPreviousTab` action.
* `showAllTabs` - Map to the `showAllTabs` action.
* `mergeAllWindows` - Map to the `mergeAllWindows` action.
* `moveTabToNewWindow` - Map to the `moveTabToNewWindow` action.
* `window` - The submenu is a "Window" menu.
* `help` - The submenu is a "Help" menu.
* `services` - The submenu is a ["Services"](https://developer.apple.com/documentation/appkit/nsapplication/1428608-servicesmenu?language=objc) menu. This is only intended for use in the Application Menu and is _not_ the same as the "Services" submenu used in context menus in macOS apps, which is not implemented in Electron.
* `recentDocuments` - The submenu is an "Open Recent" menu.
* `clearRecentDocuments` - Map to the `clearRecentDocuments` action.
* `shareMenu` - The submenu is [share menu][ShareMenu]. The `sharingItem` property must also be set to indicate the item to share.

When specifying a `role` on macOS, `label` and `accelerator` are the only
options that will affect the menu item. All other options will be ignored.
Lowercase `role`, e.g. `toggledevtools`, is still supported.

> [!NOTE]
> The `enabled` and `visibility` properties are not available for top-level menu items in the tray on macOS.

### Instance Properties

The following properties are available on instances of `MenuItem`:

#### `menuItem.id`

A `string` indicating the item's unique id, this property can be
A `string` indicating the item's unique id. This property can be
dynamically changed.

#### `menuItem.label`
Expand All @@ -165,7 +96,10 @@ item's submenu, if present.

#### `menuItem.type`

A `string` indicating the type of the item. Can be `normal`, `separator`, `submenu`, `checkbox` or `radio`.
A `string` indicating the type of the item. Can be `normal`, `separator`, `submenu`, `checkbox`, `radio`, `header` or `palette`.

> [!NOTE]
> `header` and `palette` are only available on macOS 14 and up.

#### `menuItem.role`

Expand Down Expand Up @@ -197,17 +131,17 @@ A `string` indicating the item's hover text.

#### `menuItem.enabled`

A `boolean` indicating whether the item is enabled, this property can be
A `boolean` indicating whether the item is enabled. This property can be
dynamically changed.

#### `menuItem.visible`

A `boolean` indicating whether the item is visible, this property can be
A `boolean` indicating whether the item is visible. This property can be
dynamically changed.

#### `menuItem.checked`

A `boolean` indicating whether the item is checked, this property can be
A `boolean` indicating whether the item is checked. This property can be
dynamically changed.

A `checkbox` menu item will toggle the `checked` property on and off when
Expand Down Expand Up @@ -238,5 +172,3 @@ A `number` indicating an item's sequential unique id.
#### `menuItem.menu`

A `Menu` that the item is a part of.

[ShareMenu]: https://developer.apple.com/design/human-interface-guidelines/macos/extensions/share-extensions/
Loading