‎ ‎ ‎ ‎ ‎

Electron Taskbar Badge

An easy way for electron apps to add app badges to the taskbar to indicate notifications, status, or countable items, with maximum compatibility and customizability.

Changelog (v2.0.0)

• [BREAKING]: Rename additionalFunc to onBadgeUpdate for clarity purposes. This is simply a name change.
• Font and radius is no longer a configurable option.
• Improve text fitting in badge icon. (this removes the fit option)
• Add new badge types: activity, alarm, alert, attention, error, available, busy, away, unavailable, newMessage, paused, playing.
• Negative numbers and all falsy values now clear the badge icon.
• Improve badge text centering.
• Migrate source to TypeScript.
• Expose update() as a public method on the Badge instance.

Installation

npm i electron-taskbar-badge

Basic Usage

⚠ This library only supports Windows at the moment!

First, you must import the library using the following code:

const Badge = require('electron-taskbar-badge');
// or `import * as Badge from 'electron-taskbar-badge';` for ESM users

For basic usage, all you have to do is call the function with the options:

Process: Main

const Badge = require('electron-taskbar-badge');
// or `import * as Badge from 'electron-taskbar-badge';` for ESM users

const badgeOptions = {
	fontColor: '#FFFFFF', // The font color
	color: '#FF0000', // The background color
	updateBadgeEvent: 'notificationCount', // The IPC event name to listen on
	badgeDescription: 'Unread Notifications', // The badge description
	invokeType: 'handle', // The IPC event type
	max: 9, // The maximum integer allowed for the badge. Anything above this will have "+" added to the end of it.
	onBadgeUpdate: (count) => {
		// Called whenever the badge is updated. count is the value set (number, badge type string, or null when cleared).
		console.log(`Badge updated: ${count}`);
	},
};

// "win" would be your Electron BrowserWindow object
new Badge(win, badgeOptions);

Process: Renderer

// If invokeType is set to "handle"
// Replace 8 with whatever number or badge type you want the badge to display
ipcRenderer.invoke('notificationCount', 8);

// If invokeType is set to "send"
ipcRenderer.send('notificationCount', 8);

To clear the badge, simply pass a falsy value or a negative integer.

That's it! Now you have it running!

More examples

Badge types

Instead of a number, you can pass one of the following string values to display a glyph badge:

| Type | Icon | Description | |------|------|-------------| | activity | 🔄 | Activity indicator | | alarm | 🕭 | Alarm indicator | | alert | ! | Alert indicator | | attention | ✱ | Attention indicator | | error | ✕ | Error indicator | | available | 🟢 | Available / online status | | busy | 🔴 | Busy / occupied status | | away | 🟡 | Away / idle status | | unavailable | ⚪ | Unavailable / offline status | | newMessage | ✉ | New message indicator | | paused | ⏸ | Paused status | | playing | ▶ | Playing / active playback |

*Emoji's are an approximate representation. See https://learn.microsoft.com/en-us/windows/apps/develop/notifications/badges for a more accurate visual.

// From the renderer
ipcRenderer.invoke('notificationCount', 'alert');

// Or directly from the main process
const badge = new Badge(win, badgeOptions);
badge.update('available');

Native look

If you want your badge to look native to the operating system, which means that it follows the default OS's font and color, you can use the useSystemAccentTheme option. Here's an example:

// When useSystemAccentTheme is true, the background color would be the system accent color, and the font color would be automatically chosen between black or white, which ever looks best.
const badgeOptions = {
	updateBadgeEvent: 'notificationCount',
	badgeDescription: 'Unread Notifications',
	invokeType: 'handle',
	max: 9,
	useSystemAccentTheme: true,
	onBadgeUpdate: (count) => {
		console.log(`Received ${count} new notifications!`);
	},
};

new Badge(win, badgeOptions);

Examples

Auto font color

If you want your badge's font color to be automatically chosen, simply set fontColor to auto. This will choose the font color between black or white, whichever looks best. Here's an example:

const badgeOptions = {
	fontColor: 'auto',
	color: '#00FF00',
	updateBadgeEvent: 'notificationCount',
	badgeDescription: 'Unread Notifications',
	invokeType: 'handle',
	max: 9,
	onBadgeUpdate: (count) => {
		console.log(`Received ${count} new notifications!`);
	},
};

new Badge(win, badgeOptions);

Options

Options info for Badge(options)

| Parameters | Type | Description | Default | |---------------|---------|----------------------------------------|---------| | fontColor | string | The font color in hex or RGB color format. When useSystemAccentTheme is true, this is always set to auto. | auto | | color | string (required) | The background color for the badge icon in hex or RGB color format. When useSystemAccentTheme is true, this is ignored. | null | | updateBadgeEvent | string (required) | The IPC event name to listen on | null | | badgeDescription | string | A description that will be provided to accessibility screen readers | this.updateBadgeEvent | | invokeType | string | The IPC event type. Can be send or handle. | send | | max | number | The maximum integer allowed for the badge. Anything above this will have "+" added to the end of it. | 9 | | useSystemAccentTheme | boolean | Whether to use the system accent color for the background color. fontColor and color will be overridden. It would be automatically chosen between black or white, whichever looks best. | false | | onBadgeUpdate | function(count: number | BadgeType | null) | An additional function to run whenever the IPC event fires. Receives the value the badge was set to, or null when cleared. | null |