@capawesome/capacitor-badge

v8.0.4

Published

a month ago

Capacitor plugin to access and update the badge number of the app icon on Android, iOS, and Web.

Capacitor Badge Plugin

Capacitor plugin to access and update the badge number of the app icon.

Features

The Capacitor Badge plugin is one of the most complete app icon badge solutions for Capacitor apps. Here are some of the key features:

🖥️ Cross-platform: Supports Android, iOS, and Web (PWA).
🔢 Badge management: Get, set, increase, decrease, and clear badge counts.
💾 Persistent badges: Badge count persists after reboot or app restart.
🔄 Auto-clear option: Automatically reset counter when resuming the app.
🔐 Permission handling: Check and request badge display permissions.
⚙️ Configurable: Customize persistence and auto-clear behaviors.
🤝 Compatibility: Works alongside the App Icon and Firebase Cloud Messaging plugins.
🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The Badge plugin is typically used to show a count on the app icon that reflects pending items, for example:

Unread messages: Show the number of unread chat messages or emails on the app icon.
Pending notifications: Keep the badge in sync with the notifications the user has not yet seen.
Open tasks: Display the number of open to-dos, reminders, or items in a shopping cart.
Automatic reset: Clear the counter automatically when the user resumes the app using the autoClear configuration option.

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | >=8.x.x | Active support | | 7.x.x | 7.x.x | Deprecated | | 6.x.x | 6.x.x | Deprecated | | 5.x.x | 5.x.x | Deprecated |

Demo

A working example can be found here: robingenz/capacitor-plugin-demo

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-badge` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-badge
npx cap sync

Android

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

$shortcutBadgerVersion version of me.leolin:ShortcutBadger (default: 1.1.22)

This can be useful if you encounter dependency conflicts with other plugins in your project.

iOS

Privacy manifest

Add the NSPrivacyAccessedAPICategoryUserDefaults dictionary key to your Privacy Manifest (usually ios/App/PrivacyInfo.xcprivacy):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <!-- Add this dict entry to the array if the file already exists. -->
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>CA92.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

Configuration

These configuration values are available:

| Prop | Type | Description | Default | | --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | persist | boolean | Configure whether the plugin should restore the counter after a reboot or app restart. Only available on Android and iOS. | true | | autoClear | boolean | Configure whether the plugin should reset the counter after resuming the application. On iOS, this will also clear all notifications. Only available on Android and iOS. | false |

Examples

In capacitor.config.json:

{
  "plugins": {
    "Badge": {
      "persist": true,
      "autoClear": false
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capawesome/capacitor-badge" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Badge: {
      persist: true,
      autoClear: false,
    },
  },
};

export default config;

Usage

The following examples show how to get, set, increase, decrease, and clear the badge count, check whether badges are supported, and check and request permissions.

Get the current badge count

Read the current badge count. The count won't be lost after a reboot or app restart:

import { Badge } from '@capawesome/capacitor-badge';

const get = async () => {
  const result = await Badge.get();
  return result.count;
};

Set the badge count

Set the badge count to a specific value. On iOS, setting the count to 0 will remove the badge and also clear all notifications:

import { Badge } from '@capawesome/capacitor-badge';

const set = async (count: number) => {
  await Badge.set({ count });
};

Increase or decrease the badge count

Increment or decrement the badge count by one, for example when a new message arrives or is read:

import { Badge } from '@capawesome/capacitor-badge';

const increase = async () => {
  await Badge.increase();
};

const decrease = async () => {
  await Badge.decrease();
};

Clear the badge count

Remove the badge from the app icon. On iOS, this will also clear all notifications:

import { Badge } from '@capawesome/capacitor-badge';

const clear = async () => {
  await Badge.clear();
};

Check if badges are supported

Check whether the badge count is supported on the current device, for example since not every Android launcher supports badges:

import { Badge } from '@capawesome/capacitor-badge';

const isSupported = async () => {
  const result = await Badge.isSupported();
  return result.isSupported;
};

Check and request permissions

Check and request the permission to display the badge:

import { Badge } from '@capawesome/capacitor-badge';

const checkPermissions = async () => {
  const result = await Badge.checkPermissions();
};

const requestPermissions = async () => {
  const result = await Badge.requestPermissions();
};

API

get()

get() => Promise<GetBadgeResult>

Get the badge count. The badge count won't be lost after a reboot or app restart.

Default: 0.

Returns: Promise<GetBadgeResult>

set(...)

set(options: SetBadgeOptions) => Promise<void>

Set the badge count.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | SetBadgeOptions |

increase()

increase() => Promise<void>

Increase the badge count.

decrease()

decrease() => Promise<void>

Decrease the badge count.

clear()

clear() => Promise<void>

Clear the badge count.

On iOS, this will remove the badge and also clear all notifications.

isSupported()

isSupported() => Promise<IsSupportedResult>

Check if the badge count is supported.

Returns: Promise<IsSupportedResult>

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permission to display badge.

Returns: Promise<PermissionStatus>

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to display badge.

Returns: Promise<PermissionStatus>

Interfaces

GetBadgeResult

| Prop | Type | | ----------- | ------------------- | | count | number |

SetBadgeOptions

| Prop | Type | Description | | ----------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | count | number | The badge count to set. On iOS, setting the count to 0 will remove the badge and also clear all notifications. |

IsSupportedResult

| Prop | Type | | ----------------- | -------------------- | | isSupported | boolean |

PermissionStatus

| Prop | Type | Description | | ------------- | ----------------------------------------------------------- | ----------------------------------------- | | display | PermissionState | Permission state of displaying the badge. |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Quirks

On Android there is no official API to set a badge, so not all launchers support badges. This plugin uses ShortcutBadger, which relies on vendor-specific mechanisms. All supported launchers are listed there. On stock Android launchers, such as the Pixel Launcher, no badge is displayed.

On Web, the app must run as an installed PWA (in the taskbar or dock).

FAQ

Why is the badge not showing on my Android device?

Android provides no official API to set a badge on the launcher icon. This plugin therefore uses ShortcutBadger under the hood, which relies on vendor-specific mechanisms offered by some manufacturers (such as Samsung, Xiaomi, HTC and Sony). Only the launchers listed as supported launchers can display the badge. On stock Android launchers, most notably the Pixel Launcher, no badge is displayed. You can use the isSupported() method to check whether badges are supported on the current device.

Can the plugin display an Android notification badge (dot) instead?

No. Since Android 8.0, the launcher displays a notification badge only while the app has an active notification. The badge is derived from that notification and disappears as soon as the notification is dismissed, so it cannot be set independently of one. On stock Android it is also a dot without a count. If your app already displays notifications, the badge is shown automatically without any plugin call.

Does the badge count persist after a reboot or app restart?

Yes, by default the badge count is restored after a reboot or app restart. You can disable this behavior by setting the persist configuration option to false, see the Configuration section.

How can I automatically clear the badge when the app is resumed?

Set the autoClear configuration option to true to reset the counter after resuming the application. Note that on iOS, this will also clear all notifications. See the Configuration section for an example.

Why does `checkPermissions()` always return `granted` on Android and Web?

Only iOS requires a permission to display a badge. On Android and Web no permission is needed, so the permission state is always granted.

Why does clearing the badge also remove my notifications on iOS?

On iOS, calling clear() or setting the badge count to 0 removes the badge and also clears all notifications. This is platform behavior and cannot be changed by the plugin.

Does this plugin work on the Web?

Yes, but the app must run as an installed PWA (in the taskbar or dock). Also make sure to check whether the browser supports badges using the isSupported() method.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

App Icon: Change the app icon at runtime.
App Shortcuts: Manage app shortcuts and quick actions.
Firebase Cloud Messaging: Receive push notifications via Firebase Cloud Messaging.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

Credits

This plugin is based on the Capacitor Badge plugin. Thanks to everyone who contributed to the project!