Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/capawesome-team/capacitor-badge

⚡️ Capacitor plugin to access and update the badge number of the app icon.
https://github.com/capawesome-team/capacitor-badge

List: capacitor-badge

android capacitor capacitor-android capacitor-community capacitor-ios capacitor-plugin capawesome ios pwa web

Last synced: 24 days ago
JSON representation

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

Host: GitHub
URL: https://github.com/capawesome-team/capacitor-badge
Owner: capawesome-team
License: mit
Archived: true
Created: 2021-03-20T13:48:13.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2023-04-01T07:18:38.000Z (over 1 year ago)
Last Synced: 2024-10-29T16:20:23.007Z (about 1 month ago)
Topics: android, capacitor, capacitor-android, capacitor-community, capacitor-ios, capacitor-plugin, capawesome, ios, pwa, web
Language: Swift
Homepage: https://capawesome.io/plugins/badge/
Size: 998 KB
Stars: 73
Watchers: 5
Forks: 4
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

awesome-capacitor - Badge - Access and update the badge number of the app icon. ([Capawesome plugins](https://capawesome.io/))

README

        ## ⚠️ Deprecated repository

**This project has been moved to the following monorepo: [capawesome-team/capacitor-plugins](https://github.com/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](https://github.com/robingenz) | [@robin_genz](https://twitter.com/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](https://github.com/sponsors/capawesome-team).  

## Installation

```bash

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`:

```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](https://github.com/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()`](#get)

* [`set(...)`](#set)

* [`increase()`](#increase)

* [`decrease()`](#decrease)

* [`clear()`](#clear)

* [`isSupported()`](#issupported)

* [`checkPermissions()`](#checkpermissions)

* [`requestPermissions()`](#requestpermissions)

* [Interfaces](#interfaces)

* [Type Aliases](#type-aliases)

### get()

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

--------------------

### set(...)

```typescript

set(options: SetBadgeOptions) => Promise

```

Set the badge count.

| Param         | Type                                                        |

| ------------- | ----------------------------------------------------------- |

| **`options`** | SetBadgeOptions |

--------------------

### increase()

```typescript

increase() => Promise

```

Increase the badge count.

--------------------

### decrease()

```typescript

decrease() => Promise

```

Decrease the badge count.

--------------------

### clear()

```typescript

clear() => Promise

```

Clear the badge count.

--------------------

### isSupported()

```typescript

isSupported() => Promise

```

Check if the badge count is supported.

**Returns:** Promise<IsSupportedResult>

--------------------

### checkPermissions()

```typescript

checkPermissions() => Promise

```

Check permission to display badge.

**Returns:** Promise<PermissionStatus>

--------------------

### requestPermissions()

```typescript

requestPermissions() => Promise

```

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](https://github.com/leolin310148/ShortcutBadger). All supported launchers are listed [there](https://github.com/leolin310148/ShortcutBadger#supported-launchers).

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

## Changelog

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-badge/blob/main/CHANGELOG.md).

## License

See [LICENSE](https://github.com/capawesome-team/capacitor-badge/blob/main/LICENSE).