@capawesome/capacitor-badge
v8.0.0TypeScript
Capacitor plugin to access and update the badge number of the app icon.
37.2K/weekUpdated 1 months agoMITUnpacked: 63.8 KB
Published by Robin Genz
npm install @capawesome/capacitor-badge@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
``bash`
npm install @capawesome/capacitor-badge
npx cap sync
$3
#### 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.
$3
#### Privacy manifest
Add the NSPrivacyAccessedAPICategoryUserDefaults dictionary key to your Privacy Manifest (usually ios/App/PrivacyInfo.xcprivacy):
`xml`
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 |
$3
In capacitor.config.json:
`json`
{
"plugins": {
"Badge": {
"persist": true,
"autoClear": false
}
}
}
In capacitor.config.ts:
`ts
///
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
`typescript
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
$3
`typescript`
get() => Promise
Get the badge count.
The badge count won't be lost after a reboot or app restart.
Default: 0.
Returns: Promise<GetBadgeResult>
--------------------
$3
`typescript`
set(options: SetBadgeOptions) => Promise
Set the badge count.
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| options | SetBadgeOptions |
--------------------
$3
`typescript`
increase() => Promise
Increase the badge count.
--------------------
$3
`typescript`
decrease() => Promise
Decrease the badge count.
--------------------
$3
`typescript`
clear() => Promise
Clear the badge count.
On iOS, this will remove the badge and also clear all notifications.
--------------------
$3
`typescript`
isSupported() => Promise
Check if the badge count is supported.
Returns: Promise<IsSupportedResult>
--------------------
$3
`typescript`
checkPermissions() => Promise
Check permission to display badge.
Returns: Promise<PermissionStatus>
--------------------
$3
`typescript`
requestPermissions() => Promise
Request permission to display badge.
Returns: Promise<PermissionStatus>
--------------------
$3
#### 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. |
$3
#### 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!