badge_kit 0.1.0

A Flutter plugin to update the app icon badge and clear notifications through a single API. Swift Package Manager only on iOS.

badge_kit

A Flutter plugin that provides badge updating and badge / notification clearing through a single API.

Supports Android and iOS. On iOS this plugin is Swift Package Manager (SPM) only — no CocoaPods, no Podfile changes, ready for Flutter's SPM-first future.

On Android the plugin deliberately ships no legacy launcher hacks: modern launchers show a notification dot automatically, so numeric badge control is iOS-only and notification clearing works on both platforms.

Requirements

• iOS: Flutter 3.44 or later, where Swift Package Manager is enabled by default. CocoaPods-only projects are not supported — this plugin ships no podspec.
• Android: no special setup.

Features

API	Description
BadgeKit.setBadge(int count)	Set the app icon badge count (0 clears it). iOS only; no-op on Android.
BadgeKit.clearBadge({bool removeNotifications})	Clear the badge; optionally also remove all notifications from the notification center.
BadgeKit.isBadgeSupported()	Whether numeric badges can be set (true on iOS, false on Android).
BadgeKit.clearAllNotifications()	Remove all delivered notifications from the notification center.
BadgeKit.clearNotificationsByTag(String tag)	Remove delivered notifications with a specific tag.
BadgeKit.clearNotificationsByTags(List<String> tags)	Remove delivered notifications matching any of the given tags in a single pass.

Usage

import 'package:badge_kit/badge_kit.dart';

// Set the badge to 5.
await BadgeKit.setBadge(5);

// Clear the badge but keep notifications in the notification center.
await BadgeKit.clearBadge();

// Clear the badge AND remove all notifications from the center.
await BadgeKit.clearBadge(removeNotifications: true);

// Remove all delivered notifications (badge unchanged).
await BadgeKit.clearAllNotifications();

// Remove only notifications tagged 'chat'.
await BadgeKit.clearNotificationsByTag('chat');

// Remove notifications tagged 'chat' or 'news' in one call.
await BadgeKit.clearNotificationsByTags(['chat', 'news']);

// Whether numeric badges can be set (true on iOS, false on Android).
final supported = await BadgeKit.isBadgeSupported();

Platform notes

iOS

• SPM only: the plugin is distributed as a Swift Package. There is no podspec, so your app does not need CocoaPods at all if all your plugins support SPM.

• setBadge requests badge permission on first use.

• On iOS 16+ the modern UNUserNotificationCenter.setBadgeCount API is used, so changing the badge never touches the notification center. On older versions the plugin uses the -1 trick to clear the badge without removing notifications.

• clearNotificationsByTag matches notifications whose payload contains a "tag" key with the given value, e.g.:

  {
    "aps": { "alert": "...", "badge": 1 },
    "tag": "chat"
  }
  

  Notifications whose thread-id equals the tag are matched as well.

Android

• Numeric badges are intentionally not supported. Since Android 8.0, launchers show a notification dot whenever the app has active notifications; there is no public API to set a number, and the old launcher-specific hacks (Samsung/Huawei/Xiaomi broadcasts and content providers) are unreliable or blocked on current OS versions. setBadge is a no-op and isBadgeSupported() returns false. No launcher permissions are added to your manifest.
• The notification dot disappears when the notifications are removed, so use clearBadge(removeNotifications: true) or the clearNotifications* methods.
• clearNotificationsByTag / clearNotificationsByTags match the notification tag (NotificationManagerCompat.notify(tag, id, notification) or the FCM android.notification.tag field). Requires Android 6.0+.

Comparison with similar packages

How badge_kit compares to app_badge_plus, eraser and fcm_eraser_plus (as of their latest versions in September 2026):

	badge_kit	app_badge_plus	eraser	fcm_eraser_plus
Set badge count (iOS)	✅ ¹	✅	❌ (reset only)	✅ ²
Set badge count (Android launchers)	❌ ³	✅	❌	❌
Clear badge, keep notifications (iOS)	✅	❌	✅	❌
Remove all delivered notifications	✅	❌	✅	✅
Remove notifications by tag	✅ multiple tags	❌	✅ single tag	✅ multiple tags
iOS tag matching	payload tag key or thread-id	—	apns-collapse-id	apns-collapse-id
List active notification tags	❌	❌	❌	✅
iOS distribution	SPM only	CocoaPods + SPM	CocoaPods	CocoaPods
macOS support	❌	✅	❌	❌

¹ Requests badge permission on first use and reports errors back to Dart; uses UNUserNotificationCenter.setBadgeCount on iOS 16+. ² Sets the badge via the legacy applicationIconBadgeNumber API and can optionally clear all notifications at the same time. ³ Intentionally omitted — see Platform notes.

In short: pick app_badge_plus if you need numeric badges on Android launchers or macOS, fcm_eraser_plus if you need to list active tags, and badge_kit if you want badge control plus fine-grained notification clearing in one modern, SPM-only plugin.

Example

See example/lib/main.dart for a demo app. It can send test notifications tagged chat / news (via flutter_local_notifications) and then erase them with this plugin.