npm:@robingenz/capacitor-badge

README

Badge

@robingenz/capacitor-badge

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

Maintainers

Maintainer	GitHub	Social
Robin Genz	robingenz	@robin_genz

Installation

npm install @robingenz/capacitor-badge
npx cap sync

Android Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

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

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 for Android and iOS.	`true`
`autoClear`	`boolean`	Configure whether the plugin should reset the counter after resuming the application. Only available for Android and iOS.	`false`

Examples

In capacitor.config.json:

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

In capacitor.config.ts:

/// <reference types="@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 '@robingenz/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();
};

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.

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
`count`	`number`

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.

Changelog

See CHANGELOG.md.

License

See LICENSE.

Usage no npm install needed!