[![CI Workflow][ci-workflow-badge]][github-actions] [![Release Workflow][release-workflow-badge]][github-actions] [![Renovate enabled][renovate-badge]][renovate] [![Contributors][contributors-badge]][github] [![Downloads - Year][downloads-badge]][npmjs] [![OSS License][license-badge]][license] [![NPM Latest Version][npmjs-version-badge]][npmjs] [![Latest Release][github-release-badge]][github-releases] ![Libraries.io dependency status for GitHub repo][librariesio-badge] ![npm minzipped bundle size][size-minzip-badge] ![npm minified bundle size][size-minified-badge]
➖ electron-menubar
formerly known as menubar
High level way to create menubar desktop applications with Electron.
## Features
- ⚡️ Quick start for creating menubar applications using Electron.
- 🚀 Zero runtime dependencies.
- 💻 Works on macOS, Windows and *most* Linux distributions. See [tested platforms][platforms].
| 
| 
| 
|
| :-----------------------------------------------------------: | :--------------------------------------------------------: | :------------------------------------------------------: |
| macOS | Windows 10 | Ubuntu |
> [!NOTE]
> On native Wayland, the desktop compositor controls window placement, so the popover cannot be anchored to the tray icon and is positioned by the desktop (usually centered). This is a Wayland limitation, not something the library can override. Tray-relative positioning works under X11/XWayland. See [window positioning on Linux][platforms] for the detail and a workaround.
## Installation
```bash
pnpm add electron-menubar
```
## Usage
Starting with your own new project, run these commands:
```bash
$ pnpm add electron-menubar
$ touch myApp.js
$ touch index.html
```
Fill `index.html` with some HTML, and `myApp.js` like this:
```javascript
const { menubar } = require('electron-menubar');
const mb = menubar();
mb.on('ready', () => {
console.log('app is ready');
// your app code here
});
```
Then use `electron` to run the app:
```bash
$ electron myApp.js
```
## Examples
See [`examples`][examples] folder for a selection of working examples.
## API Documentation
### `Menubar` Class
The return value of `menubar()` is a `Menubar` class instance, which exposes the following properties and methods.
#### Properties
| Property | Description |
| --- | --- |
| `app` | The [Electron App][electron-docs-app] instance. |
| `window` | The [Electron Browser Window][electron-docs-browserwindow] instance. |
| `tray` | The [Electron Tray][electron-docs-tray] instance. |
| `positioner` | The `Positioner` instance used to compute the window's on-screen coordinates. |
#### Methods
| Method | Description |
| --- | --- |
| `setOption(option, value)` | Change an option after menubar is created. |
| `getOption(option)` | Get a menubar option. |
| `showWindow()` | Show the menubar window. |
| `hideWindow()` | Hide the menubar window. |
| `toggleWindow()` | Show the window if hidden, hide it if visible. |
| `recenterOnTray()` | Re-center the window over the tray icon. |
| `setContextMenu(menu)` | Replace the tray context menu (auto-re-publishes on Linux). |
| `refreshContextMenu()` | Re-publish the current context menu after mutating its items in place. Required on Linux, a no-op elsewhere. |
| `setGlobalShortcut(accelerator)` | Register a global accelerator that toggles the window. Returns `false` on registration failure. |
| `destroy()` | Tear down the menubar instance. |
| `isDestroyed()` | Whether the menubar is currently destroyed. |
### `menubar()` Options
You can pass an optional options object into the `menubar({ ... })` function:
| Option | Default | Description |
| --- | --- | --- |
| `dir` | `process.cwd()` | The app source directory. |
| `index` | `file:// + opts.dir + index.html` | The URL to load the menubar's `browserWindow` with. The url can be a remote address (e.g. `http://`) or a path to a local HTML file using the `file://` protocol. |
| `browserWindow` | | BrowserWindow options passed to the BrowserWindow constructor, see [Electron docs][electron-docs-browserwindow-options]. Useful fields
• `x` (default `undefined`) - the x position of the window
• `y` (default `undefined`) - the y position of the window
• `width` (default `400`) - window width
• `height` (default `400`) - window height
• `alwaysOnTop` (default `false`) - if `true`, the window will not hide on blurHiding reliably
When `false`, the library calls [`app.dock.hide()`](https://www.electronjs.org/docs/latest/api/app#appdockhide-macos) at startup and re-asserts it once shortly after, because macOS can silently drop the underlying process transform when it races the launch activation. The transform only runs after the process has already launched as a regular dock app, so the tile briefly exists on every launch and hiding it stays best-effort. Packaged apps that never want a dock tile should also declare [`LSUIElement`](https://developer.apple.com/documentation/bundleresources/information-property-list/lsuielement) in their `Info.plist` (with electron-builder: `mac.extendInfo.LSUIElement: true`), so the process starts as an agent app and no tile is ever created. `showDockIcon: false` then still covers development runs, where the stock Electron binary's plist is not under your control.Platform behavior
On Linux it is bound via `tray.setContextMenu` (required by libappindicator / StatusNotifierItem) and re-published on every show/hide to defeat the indicator's menu cache. On macOS and Windows it pops up on right-click via `tray.popUpContextMenu`, so left-click continues to toggle the window. Combine with `trigger: 'none'` if you want right-click to be the only interaction.Platform notes
On Linux/Wayland the hide is deferred via `setImmediate` to work around a compositor bug that leaves frameless surfaces in a half-closed state when hidden synchronously from the `close` handler. The library tracks the app's `before-quit` event and the auto updater's `before-quit-for-update` event internally, so real quits and update restarts go through unimpeded.