app_badger

A Flutter plugin for app icon badge counts on Android, iOS, and macOS.

This repository was built as an independent badge plugin for app-level badge management. The API is kept distinct from common badge plugin names to reduce naming collisions while still supporting the standard launcher and platform behaviors expected by mobile apps.

What this package does

  • Updates numeric app badges on supported Android launchers
  • Supports iOS badge updates through the native notification system
  • Supports macOS Dock badge updates via the native Dock tile API
  • Exposes a small, consistent Dart API for set, clear, query and permission flows
  • Includes lifecycle helpers and a native event stream for app-level badge syncing

Key API

import 'package:app_badger/app_badger.dart';

await AppBadgeController.setBadgeValue(7);
await AppBadgeController.clearBadgeValue();
final count = await AppBadgeController.getBadgeValue();
final granted = await AppBadgeController.requestBadgePermission();

Legacy names remain available as deprecated wrappers for compatibility:

await AppBadger.updateBadgeCount(7);
await AppBadger.removeBadge();

Installation

Add the package to your app:

dependencies:
  app_badger: ^3.1.2

Then run:

flutter pub get

Platform setup

Android

Add notification permission for Android 13+:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Some launchers also support additional manufacturer-specific permissions. These can be added as needed for your target device.

iOS

Add the usage description to ios/Runner/Info.plist:

<key>NSUserNotificationUsageDescription</key>
<string>Notifications are required to display app badges</string>

macOS

No special entitlement is required for Dock badges. The package updates the native Dock tile badge directly.

import 'package:app_badger/app_badger.dart';

Future<void> initializeBadges() async {
  final granted = await AppBadgeController.requestBadgePermission();
  if (granted) {
    await AppBadgeController.setBadgeValue(1);
  }
}

Event stream

AppBadgeController.events.listen((event) {
  print('Badge event: $event');
});

Android notification configuration

AppBadgeController.setAndroidNotificationConfig(
  channelId: 'app_badger_channel',
  channelName: 'Badge updates',
  smallIcon: 'ic_stat_notify_badge',
);

Monorepo management

This repository uses Melos for the workspace setup and validation workflow.

melos run get
melos run analyze
melos run test
melos run format
melos run clean

This project is an independent Flutter badge package. It is not presented as a fork of, or as a direct copy of, the upstream flutter_app_badger project.

This package includes Android launcher badge support through ShortcutBadger, which remains under its own Apache 2.0 license. The project continues to keep dependency notices with the source.

License

MIT

Libraries

app_badger