> ## Documentation Index
> Fetch the complete documentation index at: https://electron-menubar.gitify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# menubar() options: window, tray, position, and triggers

> Every option accepted by menubar(): app directory, index URL, BrowserWindow settings, tray icon, window position, triggers, context menu, and shortcuts.

You can pass an optional options object into the `menubar({ ... })` function. Most options are read when the window or tray is created; some, such as `hideOnBlur`, can also be changed later with `mb.setOption(option, value)`.

```javascript theme={null}
const mb = menubar({
  index: 'https://example.com',
  browserWindow: { width: 400, height: 400 },
  windowPosition: 'trayCenter',
  hideOnClose: true,
  escapeToHide: true,
});
```

## App and content

**dir** `string` (default: process.cwd())

The app source directory.

**index** `string | false` (default: 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. If `false`, then menubar won't call `loadURL` on start.

**loadUrlOptions** `LoadURLOptions` (default: undefined)

The options passed when loading the index URL in the menubar's
`browserWindow`. Everything `browserWindow.loadURL` supports is supported;
this object is simply passed onto
[browserWindow.loadURL](https://electronjs.org/docs/api/browser-window#winloadurlurl-options).

## Window

**browserWindow** `BrowserWindowConstructorOptions`

BrowserWindow options passed to the BrowserWindow constructor, see [Electron docs](https://electronjs.org/docs/api/browser-window#new-browserwindowoptions).

**useful fields**

**x** `number` (default: undefined)

The x position of the window.

**y** `number` (default: undefined)

The y position of the window.

**width** `number` (default: 400)

Window width.

**height** `number` (default: 400)

Window height.

**alwaysOnTop** `boolean` (default: false)

Keeps the window on top without changing click-away dismissal; Windows popups are always raised above the tray.

**preloadWindow** `boolean` (default: false)

Create
[BrowserWindow](https://electronjs.org/docs/api/browser-window#new-browserwindowoptions)
instance before it is used, increasing resource usage but making the click on
the menubar load faster.

**windowPosition** `WindowPosition` (default: trayCenter (macOS/Linux), trayBottomCenter (Windows))

Sets the window position (`browserWindow.x` / `browserWindow.y` will still
override this). Valid values: `trayLeft`, `trayBottomLeft`, `trayRight`,
`trayBottomRight`, `trayCenter`, `trayBottomCenter`, `topLeft`, `topRight`,
`bottomLeft`, `bottomRight`, `topCenter`, `bottomCenter`, `leftCenter`,
`rightCenter`, `center`.

**showOnAllWorkspaces** `boolean` (default: true)

Makes the window available on all macOS workspaces. On macOS the window leaves
all workspaces while hidden and rejoins them on `showWindow()`, so show it
with `showWindow()` rather than `window.show()` or `window.showInactive()`.

**hideOnBlur** `boolean` (default: true)

Set `false` to keep the popup open and on top, emitting `focus-lost` on
click-away. Defaults to `true`. DevTools temporarily suspends dismissal
without changing this preference. Supports runtime changes through
`setOption`. See [Popup Behavior](https://electron-menubar.gitify.io/guides/popup-behavior.md).

**hideOnClose** `boolean` (default: false)

Hide the window on `close` instead of destroying it, so the next tray click re-uses the same `BrowserWindow`.

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.

**escapeToHide** `boolean` (default: false)

Hide the menubar window when the user presses `Escape` while it has focus.

## Tray

**icon** `string | NativeImage` (default: opts.dir + IconTemplate.png)

The png icon to use for the menubar. A good size to start with is 20x20. To
support retina, supply a 2x sized image (e.g. 40x40) with `@2x` added to the
end of the name, so `icon.png` and `icon@2x.png`, and Electron will
automatically use your `@2x` version on retina screens.

**tooltip** `string` (default: empty)

Menubar tray icon tooltip text.

**tray** `Tray` (default: created on-the-fly)

An Electron `Tray` instance. If provided, `opts.icon` will be ignored.

**trigger** `'click' | 'right-click' | 'none'` (default: 'click')

Tray event that toggles the menubar window. Use `'none'` to disable automatic
toggling, useful when a single tray icon serves multiple windows. The window
can still be shown by calling `mb.showWindow()` directly.

**showOnRightClick** `boolean` *deprecated* (default: false)

**Deprecated**, use `trigger: 'right-click'` instead. Show the window on
`right-click` event instead of regular `click`.

**contextMenu** `Menu`

An Electron `Menu` to attach to the tray icon. 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. See [Context
Menus](https://electron-menubar.gitify.io/guides/context-menus.md).

**ignoreDoubleClickEvents** `boolean` (default: true (macOS only))

Calls `tray.setIgnoreDoubleClickEvents(true)` so an accidental double-click
doesn't race the close-on-blur handler and flicker the tray icon. Pass `false`
to opt out. No-op on Linux/Windows.

## App behavior

**showDockIcon** `boolean` (default: false)

Configure the visibility of the application dock icon, macOS only.

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.

**activateWithApp** `boolean` (default: true)

Listen on `app.on('activate')` to open menubar when app is activated.

**globalShortcut** `Accelerator`

An [Accelerator](https://electronjs.org/docs/api/accelerator) string
registered as a global keyboard shortcut that toggles the menubar window.
Unregistered automatically on `destroy()`. Use
`mb.setGlobalShortcut(accelerator)` to change or clear it at runtime.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.