https://github.com/ziqq/flutter_badge_manager
Plugin to update the app badge on the launcher (both for Android, iOS and macOS)
https://github.com/ziqq/flutter_badge_manager
android flutter flutter-plugin ios macos
Last synced: 3 months ago
JSON representation
Plugin to update the app badge on the launcher (both for Android, iOS and macOS)
- Host: GitHub
- URL: https://github.com/ziqq/flutter_badge_manager
- Owner: ziqq
- License: mit
- Created: 2025-02-18T10:41:58.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-19T11:40:09.000Z (4 months ago)
- Last Synced: 2026-03-20T04:46:32.774Z (4 months ago)
- Topics: android, flutter, flutter-plugin, ios, macos
- Language: Dart
- Homepage: https://pub.dev/packages/flutter_badge_manager
- Size: 1.7 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# flutter_badge_manager
[](https://pub.dev/packages/flutter_badge_manager)
[](https://codecov.io/gh/ziqq/flutter_badge_manager)
Plugin to set / clear application badge numbers on iOS, macOS and supported Android launchers (OEM / third‑party). Stock Android (Pixel / AOSP) only shows a notification dot; numeric badges depend on the launcher.
| Platform | Min Version | Notes |
|----------|-------------|-------|
| Android | API 21+ | Numeric badge only on supported launchers; request POST_NOTIFICATIONS on API 33+. |
| iOS | 13.0+ | Uses applicationIconBadgeNumber; needs notification authorization. |
| macOS | 10.15+ | Uses dockTile.badgeLabel; needs notification authorization. |
## Features
- Unified API with automatic federated implementation selection.
- Preferred instance style (`FlutterBadgeManager.instance.update(3)`).
- `0.2.0` exposes only the instance API and federated Pigeon-backed platform implementations.
- Fails fast if no federated implementation is registered for the current platform.
- Simple support check: `isSupported()`.
## Installation
Add to `pubspec.yaml` (only top-level plugin needed):
```yaml
dependencies:
flutter_badge_manager: ^
```
Federated platform packages (Android, iOS/macOS) are auto-included when you build your app.
## iOS Setup
Request notification permission before setting a badge if you also show notifications.
Optional (for remote notification background handling) add to `ios/Runner/Info.plist`:
```xml
UIBackgroundModes
remote-notification
```
## macOS Setup
Optional banner style in `macos/Runner/Info.plist`:
```xml
NSUserNotificationAlertStyle
banner
```
## Android Notes
No official numeric badge API. Supported via OEM/third‑party launchers (Samsung, Xiaomi, Huawei, Sony, etc.). Pixel shows only dots triggered by notifications.
Android 13+ (API 33): request runtime notification permission before updating badge number.
Optional launcher permissions (add only what you really need) in `AndroidManifest.xml`:
```xml
```
## Usage
Import:
```dart
import 'package:flutter_badge_manager/flutter_badge_manager.dart';
```
Instance style (recommended):
```dart
final badge = FlutterBadgeManager.instance;
if (await badge.isSupported()) {
await badge.update(7);
await badge.remove();
}
```
For tests, bind a specific platform implementation with
`FlutterBadgeManager.instanceFor(...)` instead of relying on the shared
singleton.
For migration details, see [MIGRATION.md](MIGRATION.md).
## Permissions (recommended flow)
iOS/macOS:
- Request notification authorization (badge) via `permission_handler` or native flow before first update.
Android (API 33+):
```dart
import 'package:permission_handler/permission_handler.dart';
Future ensureNotificationPermission() async {
final status = await Permission.notification.status;
if (!status.isGranted) await Permission.notification.request();
}
```
## Constraints
- `count >= 0`; negative values throw `ArgumentError`.
- Unsupported launchers may ignore numeric changes.
- Clearing badge = `remove()` (sets label to blank / 0 depending on platform).
## Troubleshooting
- Returns false on `isSupported()` on Pixel: expected (numeric not available).
- Badge not visible on Android: launcher does not support numeric badges or permission not granted.
- iOS badge not updating: check notification authorization and that app not restricted in settings.
## Project Structure
```
flutter_badge_manager/ # App-facing package (what users depend on)
flutter_badge_manager_platform_interface/ # Platform interface (abstract contract)
flutter_badge_manager_android/ # Android implementation
flutter_badge_manager_foundation/ # iOS & macOS (Darwin) implementation
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for build commands and development workflow.
## Contributing
Issues / PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## Funding
If you want to support the development of our library, there are several ways you can do it:
- [Buy me a coffee](https://www.buymeacoffee.com/ziqq)
- [Subscribe through Boosty](https://boosty.to/ziqq)
## Coverage
