@capawesome/capacitor-badge

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

Features

We are proud to offer one of the most complete and feature-rich Capacitor plugins for app icon badge management. 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.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

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

Newsletter

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

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 |

Installation

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;

Demo

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

Usage

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

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

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

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

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

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

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

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

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

API

• get()
• set(...)
• increase()
• decrease()
• clear()
• isSupported()
• checkPermissions()
• requestPermissions()
• Interfaces
• Type Aliases

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 not all launchers support badges. This plugin uses ShortcutBadger. All supported launchers are listed there.

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

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!