flutter_native_badge
A Flutter plugin that wraps native badge APIs on iOS, macOS, and Android. Set badge counts, show a red dot indicator, clear badges, and manage notification permissions — all through a simple Dart API.
Features
- Set badge count — Display a numeric badge on your app icon
- Show red dot — Show a dot indicator without a number (macOS dock)
- Clear badge — Remove the badge from your app icon
- Get badge count — Read the current badge value
- Request permission — Handle iOS and Android notification permission prompts
- Platform check — Safely check if the current platform supports badges
Platform Support
| Feature | iOS | macOS | Android |
|---|---|---|---|
setBadgeCount() |
✅ | ✅ | ✅ |
clearBadgeCount() |
✅ | ✅ | ✅ |
showRedDot() |
❌ (no-op) | ✅ | ✅ (shows 1) |
getBadgeCount() |
⚠️ Deprecated | ✅ | ✅ (last value set) |
requestPermission() |
✅ | ✅ (no-op) | ✅ (API 33+) |
Requires Flutter 3.44 or later. iOS and macOS support both Swift Package Manager and CocoaPods.
Preview
| iOS | macOS |
|---|---|
![]() |
![]() |
Installation
Add flutter_native_badge to your pubspec.yaml:
dependencies:
flutter_native_badge: ^2.1.0
Then run:
flutter pub get
Quick Start
import 'package:flutter_native_badge/flutter_native_badge.dart';
// Check platform support first
if (FlutterNativeBadge.isSupported) {
// Request permission (shows dialog on iOS)
await FlutterNativeBadge.requestPermission();
// Set badge count
await FlutterNativeBadge.setBadgeCount(5);
// Clear badge
await FlutterNativeBadge.clearBadgeCount();
}
API Reference
Check if the platform is supported
bool isSupported = FlutterNativeBadge.isSupported;
Returns true on iOS, macOS, and Android. Returns false on all other platforms. Use this before calling any other method to avoid UnsupportedError.
Set badge count
await FlutterNativeBadge.setBadgeCount(5);
On iOS 16+, uses the modern UNUserNotificationCenter.setBadgeCount API. On earlier iOS versions, falls back to applicationIconBadgeNumber. On Android, see how Android badges work.
Show red dot
await FlutterNativeBadge.showRedDot();
Shows a red dot indicator on the app icon without displaying a number. Useful for indicating new content.
On macOS, this also bounces the dock icon until the app is activated. Android launchers can't show a dot without a count, so this sets the badge count to 1. On iOS, this is a no-op because iOS badges always show a number.
Clear badge count
await FlutterNativeBadge.clearBadgeCount();
Removes the badge from the app icon and resets the count to 0.
Get badge count
int badgeCount = await FlutterNativeBadge.getBadgeCount();
⚠️ Deprecated on iOS: This uses the
applicationIconBadgeNumberAPI which Apple has deprecated. There is no replacement in the iOS SDK. Consider managing the count yourself via your backend or local storage.
On Android, launchers can't be queried for the current badge, so this returns the last count set through this plugin.
Request permission
await FlutterNativeBadge.requestPermission();
On iOS, presents the system notification permission dialog. On Android 13+ (API 33), requests the POST_NOTIFICATIONS runtime permission. On macOS, this is a no-op.
You can also pass requestPermission: true to any method to request permission inline:
await FlutterNativeBadge.setBadgeCount(5, requestPermission: true);
await FlutterNativeBadge.showRedDot(requestPermission: true);
await FlutterNativeBadge.clearBadgeCount(requestPermission: true);
Permissions
iOS
Badge counts on iOS require notification permissions. Call requestPermission() before setting a badge, or pass requestPermission: true to individual methods. No Info.plist changes are needed.
macOS
No special permissions are required. Badge APIs work out of the box on macOS.
Android
Android has no public API for setting an app icon badge. Most launchers (Samsung One UI, Pixel, Xiaomi, OPPO, vivo, ...) only badge an app icon while the app has an active notification. The plugin handles this for you:
- Huawei and Honor launchers: the count is set directly through the launcher's badge API. No notification is shown.
- All other launchers (Android 8.0+): the plugin posts a single silent, low-priority notification that carries the count, in a notification channel named App icon badge. The notification is removed when the badge is cleared, and tapping it opens your app.
Keep in mind:
- The badge notification is visible in the notification shade, and users can dismiss it (which also removes the badge).
- How the badge looks is up to the launcher and the user's settings. Some launchers show the number, others only a dot.
- The plugin adds the
POST_NOTIFICATIONSpermission to your app's manifest. On Android 13+ (API 33), callrequestPermission()(or passrequestPermission: true) so the user can grant it. Without it, the badge isn't shown on launchers that rely on notifications. - If your app already shows its own notifications, the launcher badge counts those too.
Migrating from flutter_app_badger
flutter_app_badger has been discontinued. Here's how to migrate:
// Before (flutter_app_badger)
FlutterAppBadger.updateBadgeCount(5);
FlutterAppBadger.removeBadge();
FlutterAppBadger.isAppBadgeSupported();
// After (flutter_native_badge)
await FlutterNativeBadge.setBadgeCount(5, requestPermission: true);
await FlutterNativeBadge.clearBadgeCount();
FlutterNativeBadge.isSupported; // synchronous getter
Key differences:
flutter_native_badgeuses a federated plugin architecture for better maintainability- Built-in permission handling with
requestPermissionparameter showRedDot()for dot-only indicators on macOS- Uses modern iOS 16+ badge APIs with automatic fallback
- Works on modern Android launchers (including Samsung One UI), which ignore the legacy launcher APIs
flutter_app_badgerrelied on - Type-safe Pigeon bindings instead of raw method channels
Contributing
Contributions are welcome! Please open an issue to discuss a change before submitting a pull request, and follow the Flutter style guide.
License
MIT — see LICENSE for details.
Libraries
- flutter_native_badge
- A Flutter plugin for managing native app icon badges.

