Skip to content
This repository has been archived by the owner on Apr 1, 2023. It is now read-only.

capawesome-team/capacitor-badge

Repository files navigation

⚠️ Deprecated repository

This project has been moved to the following monorepo: capawesome-team/capacitor-plugins.



Badge

@capawesome/capacitor-badge

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


Maintainers

Maintainer GitHub Social
Robin Genz robingenz @robin_genz

Sponsors

This is an MIT-licensed open source project. It can grow thanks to the support by these awesome people. If you'd like to join them, please read more here.

Installation

npm install @capawesome/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="@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()

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.

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

Changelog

See CHANGELOG.md.

License

See LICENSE.