This module provides boilerplate for setting up a menubar application using Electron. All you have to do is point it at your index.html
and menubar
will handle the rest.
✅ Only one dependency, and one peer-dependency.
✅ Works on macOS, Windows and most Linuxes. See details.
✅ 💥 3.6kB minified + gzipped 💥
macOS Mojave 10.14 | Windows 10 | Ubuntu 18.04 |
yarn add menubar
Starting with your own new project, run these commands:
$ yarn add menubar
$ touch myApp.js
$ touch index.html
Fill index.html
with some HTML, and myApp.js
like this:
const { menubar } = require('menubar');
const mb = menubar();
mb.on('ready', () => {
console.log('app is ready');
// your app code here
});
Then use electron
to run the app:
$ electron myApp.js
Alternatively, see examples/hello-world
folder for a simple working example.
The return value of menubar()
is a Menubar
class instance, which has these properties:
-
app
: the Electron App instance, -
window
: the Electron Browser Window instance, -
tray
: the Electron Tray instance, -
positioner
: the Electron Positioner instance, -
setOption(option, value)
: change an option after menubar is created, -
getOption(option)
: get an menubar option, -
showWindow()
: show the menubar window, -
hideWindow()
: hide the menubar window
See the reference API docs.
You can pass an optional options object into the menubar({ ... })
function:
-
dir
(defaultprocess.cwd()
) - the app source directory -
index
(defaultfile:// + 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 thefile://
protocol. -
browserWindow
- BrowserWindow options to be passed to the BrowserWindow constructor, see Electron docs. Some interesting fields to passed down are:-
x
(defaultundefined
) - the x position of the window -
y
(defaultundefined
) - 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 blur
-
-
icon
(defaultopts.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, soicon.png
andicon@2x.png
and Electron will automatically use your@2x
version on retina screens. -
tooltip
(default empty) - menubar tray icon tooltip text -
tray
(default created on-the-fly) - an electronTray
instance. if providedopts.icon
will be ignored -
preloadWindow
(default false) - Create BrowserWindow instance before it is used -- increasing resource usage, but making the click on the menubar load faster. -
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 -
showOnAllWorkspaces
(default true) - Makes the window available on all OS X workspaces. -
windowPosition
(default trayCenter and trayBottomCenter on Windows) - Sets the window position (x and y will still override this), check positioner docs for valid values. -
showDockIcon
(default false) - Configure the visibility of the application dock icon. -
showOnRightClick
(default false) - Show the window on 'right-click' event instead of regular 'click'
See the reference API docs.
The Menubar
class is an event emitter:
-
ready
- whenmenubar
's tray icon has been created and initialized, i.e. whenmenubar
is ready to be used. Note: this is different than Electron app'sready
event, which happens much earlier in the process -
create-window
- the line beforenew BrowserWindow()
is called -
before-load
- after create window, before loadUrl (can be used forrequire("@electron/remote/main").enable(webContents)
) -
after-create-window
- the line after all window init code is done and url was loaded -
show
- the line beforewindow.show()
is called -
after-show
- the line afterwindow.show()
is called -
hide
- the line beforewindow.hide()
is called (on window blur) -
after-hide
- the line afterwindow.hide()
is called -
after-close
- after the.window
(BrowserWindow) property has been deleted -
focus-lost
- emitted if always-on-top option is set and the user clicks away
menubar | Electron | Notes |
---|---|---|
9.x.x | >=9.x.x <33.x.x | |
8.x.x | 8.x.xx | |
7.x.x | 7.x.xx | |
6.x.x | >=4.x.x <7.x.x | Not recommended for security reasons |
<= 5.x.x | <= 3.x.x | Please, please don't use these old versions |
See the reference API docs.
- Use
mb.on('after-create-window', callback)
to run things after your app has loaded. For example you could runmb.window.openDevTools()
to open the developer tools for debugging, or load a different URL withmb.window.loadURL()
- Use
mb.on('focus-lost')
if you would like to perform some operation when using the optionbrowserWindow.alwaysOnTop: true
- To restore focus of previous window after menubar hide, use
mb.on('after-hide', () => { mb.app.hide() } )
or similar - To create a native menu, you can use
tray.setContextMenu(contextMenu)
, and pass this custom tray to menubar:const mb = menubar({ tray });
. See this example for more information. - To avoid a flash when opening your menubar app, you can disable backgrounding the app using the following:
mb.app.commandLine.appendSwitch('disable-backgrounding-occluded-windows', 'true');