The documentation is currently a work in progress whilst the product is in alpha.

Badges

Manage the badge count on your application.

On iOS devices, the application icon on the device home screen is able to display a badge count, which appears as a red circle with a number at the top right of the icon. This number indicates how many unread notifications the application currently has.

The device does not keep track of how many unread notifications are currently on the device, therefore it is up to you to control the badge count.

Updating the badge count

Setting the badge count

To set a count for your application on the device, call the setBadgeCount method:

notifee.setBadgeCount(1).then(() => console.log('Badge count set!'));

To set the count, the value passed to the method must be an integer greater than zero.

Removing the badge count

To remove the badge and the count from the application, pass 0 to the setBadgeCount method:

notifee.setBadgeCount(0).then(() => console.log('Badge count removed!'));

Getting the badge count

To retrieve the current badge count on the device, all the getBadgeCount method:

notifee.getBadgeCount().then(count => console.log('Current badge count: ', count));

Incrementing / Decrementing

Notifee provides helper methods to increment or decrement the current badge count in a single operation.

To increment the badge count, call the incrementBadgeCount method:

// Increment by 1
notifee
  .incrementBadgeCount()
  .then(() => notifee.getBadgeCount())
  .then(count => console.log('Badge count incremented by 1 to: ', count));

By default, the count will be incremented by 1. To override this behaviour, pass the increment value as a parameter:

// Increment by 3
notifee
  .incrementBadgeCount(3)
  .then(() => notifee.getBadgeCount())
  .then(count => console.log('Badge count incremented by 3 to: ', count));

To decrement the badge count, call the decrementBadgeCount method:

// Increment by 1
notifee
  .decrementBadgeCount()
  .then(() => notifee.getBadgeCount())
  .then(count => console.log('Badge count decremented by 1 to: ', count));

By default, the count will be decremented by 1. To override this behaviour, pass the decrement value as a parameter:

// Decrement by 3
notifee
  .decrementBadgeCount(3)
  .then(() => notifee.getBadgeCount())
  .then(count => console.log('Badge count decremented by 3 to: ', count));

When decrementing, if the new value is less than 1, the badge will be removed automatically, and the returned badge count will be zero.

Integration

Generally you will only want to display a badge count when the application is not in the foreground, therefore to integrate badge count handling into your application, a Background Event can be used to control the badge count.

For example, if a notification has been delivered whilst in the background, we can increment the count. However, if the user presses the notification (or an action) we could then decrement the count, for example:

import notifee, { EventType } from '@notifee/react-native';

notifee.onBackgroundEvent(async ({ type, detail }) => {
  const { notification, pressAction } = detail;

  if (type === EventType.DELIVERED) {
    // Increment the count by 1
    await notifee.incrementBadgeCount();
  }

  // Check if the user pressed the "Mark as read" action
  if (type === EventType.ACTION_PRESS && pressAction.id === 'mark-as-read') {
    // Decrement the count by 1
    await notifee.decrementBadgeCount();

    // Remove the notification
    await notifee.cancelNotification(notification.id);
  }
});

Since the onBackgroundEvent handler only triggers when the application is not in the foreground we can safely assume the notification has not been read (unless they interact with it).

If the user opens the application it is then safe to remove the badge count entirely:

function App() {
  useEffect(() => {
    // App launched, remove the badge count
    notifee.setBadgeCount(0).then(() => console.log('Badge count removed'));
  }, []);

  ...
}

Copyright 2020 © Invertase Limited

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License and code samples are licensed under the Apache 2.0 License.

All product names, logos, and brands are property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.