When to use the badges Flutter package
The badges package is ideal whenever you need a small visual cue attached to an existing widget. Typical scenarios include notification counts on app‑bar icons, cart item counters, new‑feature dots in navigation drawers, required‑field markers in forms, or custom status indicators for live chat.
Installing the package
Add the dependency with the Flutter CLI:
flutter pub add badgesAfter the command finishes, run flutter pub get to fetch the library.
Basic usage – a beginner‑friendly example
Wrap any widget with Badge. The following minimal example shows a shopping‑cart icon with a numeric badge:
import 'package:flutter/material.dart';
import 'package:badges/badges.dart';
class BadgeDemo extends StatelessWidget {
const BadgeDemo({Key? key}) : super(key: key);
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Badges Example')),
body: Center(
child: Badge(
position: BadgePosition.topEnd(top: 0, end: 0),
badgeContent: const Text('3', style: TextStyle(color: Colors.white)),
child: const Icon(Icons.shopping_cart, size: 48),
),
),
);
}
}This code works on all Flutter platforms without additional setup.
Customizing badge appearance
The widget offers a badgeStyle property for fine‑grained control. Below is an example that changes shape, color, border, and padding:
Badge(
badgeStyle: BadgeStyle(
badgeColor: Colors.deepPurple,
shape: BadgeShape.square,
borderRadius: BorderRadius.circular(8),
borderSide: const BorderSide(color: Colors.white, width: 2),
padding: const EdgeInsets.all(6),
),
badgeContent: const Icon(Icons.check, size: 12, color: Colors.white),
child: const Icon(Icons.email, size: 48),
)All style properties are optional; omitted values fall back to sensible defaults.
Adding animation to draw attention
Badges can animate automatically. Choose a preset via animationType and control the duration with animationDuration:
Badge(
animationType: BadgeAnimationType.scale,
animationDuration: const Duration(milliseconds: 300),
badgeContent: const Text('NEW', style: TextStyle(color: Colors.white)),
child: const Icon(Icons.message, size: 48),
)Supported animation types include fade, scale, and slide. Experiment to find the most appropriate effect for your UI.
Common pitfalls and performance tips
Tip: Each
Badgeadds an extra widget layer. In lists with hundreds of items, consider usingValueListenableBuilderorAnimatedBuilderto limit rebuilds, and avoid placing badges inside heavy rebuild zones.
Other things to watch out for:
- Do not rely on the badge for critical accessibility information; always provide a textual alternative.
- The package is designed for simple overlays. For complex multi‑element overlays, you may need a custom
Stackimplementation. - If you need dynamic positioning based on screen size, compute
BadgePositionvalues at runtime rather than hard‑coding pixels.
Where to find more information
The official documentation lives on pub.dev: https://pub.dev/packages/badges. Always verify the latest API surface and version‑specific notes there.
FAQ
- Can I use badges on web and desktop? Yes. The package is pure Dart/Flutter and works across mobile, web, and desktop platforms.
- How do I hide a badge conditionally? Wrap the
Badgein a conditional expression or useVisibilityto toggle its presence without rebuilding the child widget. - Is there a way to animate the badge only when the count changes? Combine
Badgewith aValueNotifierand rebuild only when the value updates; the built‑in animation will trigger on each rebuild. - What alternatives exist if I need more complex overlays? Packages such as
flutter_badge,badges_flutter, or a customStackwith positioned widgets can handle advanced use‑cases.
Frequently Asked Questions
What is the primary purpose of the badges Flutter package?
The package provides a lightweight widget that overlays a customizable badge—such as a numeric counter, dot, or custom content—on any existing Flutter widget, simplifying notification and status indicators.
How do I install the badges package?
Run <code>flutter pub add badges</code> in your project root, then execute <code>flutter pub get</code>. Import it with <code>import 'package:badges/badges.dart';</code>.
Can I animate badges out of the box?
Yes. The widget supports built‑in animation types (fade, scale, slide) via the <code>animationType</code> property, and you can control the speed with <code>animationDuration</code>.
Is the package suitable for large lists or high‑frequency updates?
It works fine for typical use‑cases, but each badge adds an extra widget layer. For very large lists, limit rebuilds with state‑management techniques (e.g., <code>ValueListenableBuilder</code>) to avoid performance hits.
Where can I find the official documentation and latest version?
The official docs and changelog are on pub.dev at <a href="https://pub.dev/packages/badges">https://pub.dev/packages/badges</a>. Always check there for the most up‑to‑date API details.