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:

Code
flutter pub add badges

After 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:

Dart / Flutter
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:

Code
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:

Code
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 Badge adds an extra widget layer. In lists with hundreds of items, consider using ValueListenableBuilder or AnimatedBuilder to 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 Stack implementation.
  • If you need dynamic positioning based on screen size, compute BadgePosition values 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 Badge in a conditional expression or use Visibility to toggle its presence without rebuilding the child widget.
  • Is there a way to animate the badge only when the count changes? Combine Badge with a ValueNotifier and 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 custom Stack with 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.