flutter_badges 4.0.0: four shapes, six animations and the Flutter Badge name clash

A badge package whose first problem is a name collision

The badges package exists for a narrow job that Flutter apps hit constantly: showing a small count or status marker on top of another widget, in a way that looks the same on every platform. The repository description calls it "A flutter package for creating badges", and the current release is v4.0.0, published on 2026-09-24. The complication is not the badge but the collision it creates. The README states that Flutter ships its own `Badge` widget, so adding this package to an app puts two classes with the same name in scope. That is why the README spends more of its length on import mechanics than on the visual result, and it is the first thing a new user runs into.

The release history is worth reading too. The listed versions jump from 3.0.0-beta.1 in December 2022 to 4.0.0 in September 2026, and the README keeps a dedicated migration guide section for anyone arriving from Badges 2. A stable 3.x line that never shipped is not proof of neglect, but it does mean code found in older tutorials may not match the current API.

Adding badges ^4.0.0 and choosing between two import styles

The dependency goes into `pubspec.yaml` exactly as the README shows it:

dependencies:
  badges: ^4.0.0

After that you must decide how the package is imported, and the README gives two options because of the Material clash. Option 1 gives the whole package a namespace, so every class is reached through the prefix:

import 'package:badges/badges.dart' as badges;

With that line in place you write the widget as `badges.Badge` rather than `Badge`, and the same applies to every other class the package exports, including the shape and animation helpers. Option 2 imports the package plainly and hides Flutter's widget instead:

import 'package:badges/badges.dart';
import 'package:material_ui/material_ui.dart' hide Badge;
// or, if your app hasn't migrated to material_ui yet:
// import 'package:flutter/material.dart' hide Badge;

The two commented lines matter more than they look. The `hide Badge` clause targets whichever Material library your app actually imports, so a codebase that still imports Flutter's widget library directly needs the second form. Copying the first form into a project that imports Flutter's widget library without the hide clause will not resolve the collision, and the compiler will report an ambiguous import instead.

badgeContent and child are the whole contract

The smallest useful badge takes a content widget and a child to sit on:

    badges.Badge(
      badgeContent: Text('3'),
      child: Icon(Icons.settings),
    )

Nothing else is required. Position, animation and style all have defaults, and the child is left untouched by the package apart from the hit testing described below. The pairing in the example is the common case: a count rendered as text, anchored to an icon that marks a settings entry. The advanced example in the README follows the same shape with a much longer parameter list, so the widget's contract is narrow even when its configuration surface looks large. If you are evaluating the package, judge the two line version first, because it is what most apps end up shipping.

One structural detail is easy to miss: the badge is not drawn into the child's own paint order, it is stacked over it, and where the bubble lands depends on the position parameter rather than on the child.

Negative position offsets enlarge the tap target

Two parameters decide how a badge reacts to touch, and the README explains both in terms of Flutter's hit testing rules. The `onTap` note reads that when the badge sits outside its child, which the README describes as negative `position` values, the badge adds padding around the child so the whole badge can be tapped, because Flutter only delivers taps inside a widget's bounds. The padding makes the widget bigger, so the same note advises leaving `onTap` null if you do not need it. The advanced example places the badge with `badges.BadgePosition.topEnd(top: -10, end: -12)`, negative on both axes, which is exactly the case that triggers the extra padding.

This is a genuine trade-off rather than a free fix. The bubble looks like it floats above the corner of the icon, but the widget underneath has been padded to cover the bubble's area, so the surrounding layout reserves more room than the icon itself needs. The second parameter, `ignorePointer`, goes the other way: setting it to true lets taps pass through the badge to the widgets below it, and in that case `onTap` is not called. Decide which of the two behaviours you need before you position a badge outside its child.

Six animation behaviours, from colour change to rotation

The animation set is the reason many teams reach for this package at all. The README lists six behaviours in order: a colour change animation, then `BadgeAnimation.slide`, `BadgeAnimation.fade`, `BadgeAnimation.scale`, `BadgeAnimation.size` and `BadgeAnimation.rotation`. A loop mode is available on top of those, and the README notes that the loop animation runs until you stop it, so it needs an explicit control rather than ending on its own.

The rotation variant exposes the full set of knobs, and this is the block from the advanced example:

      badgeAnimation: badges.BadgeAnimation.rotation(
        animationDuration: Duration(seconds: 1),
        colorChangeAnimationDuration: Duration(seconds: 1),
        loopAnimation: false,
        curve: Curves.fastOutSlowIn,
        colorChangeAnimationCurve: Curves.easeInCubic,
      ),

Two separate durations are involved, one for the movement and one for the colour transition, each with its own curve, so a rotation can sweep around the child while the fill colour crossfades independently. `loopAnimation: false` turns off the endless repeat. Because these are ordinary Flutter `Duration` and `Curve` values, you can drive the timing from your own state rather than hardcoding seconds.

Four badge shapes and two gradient parameters

Shapes come from a fixed set of four: `BadgeShape.circle`, `BadgeShape.square`, `BadgeShape.twitter` and `BadgeShape.instagram`, the last two named after the silhouettes they imitate. Everything else about the bubble is set through `BadgeStyle`, whose parameters in the README include `shape`, `badgeColor`, `padding`, `borderRadius`, `borderSide`, `borderGradient`, `badgeGradient` and `elevation`. Gradients are built with `BadgeGradient.linear`, which takes a list of colours and optional `begin` and `end` alignments, so a top to bottom fade is expressible directly.

There is a rough edge in the printed example. The advanced snippet passes `badgeGradient` twice, once with a red to black colour list and again with a blue to yellow list and explicit alignments. Dart does not accept the same named argument twice in one call, so that block cannot be pasted whole. Copy the style in pieces and keep a single gradient argument, and expect the border gradient and the fill gradient to be separate keys that you set independently. The README does not describe how the two interact, so the reliable route is to try each one in the example app.

The repository ships an example app, tests and lint rules

The layout is that of a conventional Dart package, and it gives you a place to try the API without writing a widget from scratch. At the top level sit `pubspec.yaml`, `analysis_options.yaml`, `lib/`, `test/`, `example/`, `images/`, `CHANGELOG.md`, `LICENSE`, `README.md` and a `.github/` directory. The `analysis_options.yaml` file points at the `flutter_lints` ruleset, and the README carries a `style: flutter lints` badge, so the package is held to the standard Dart analyser configuration rather than a custom one.

The `example/` directory contains an app with `android/`, `ios/` and `windows/` platform folders alongside its own `pubspec.yaml` and `test/` directory, which is where the shapes and animations in the README's preview images come from. A CI workflow at `.github/workflows/ci.yml` is referenced by the build badge in the README header. Unusually for a widget package, the repository also carries `AGENTS.md`, `CLAUDE.md` and `PLAN.md` at the root, so the maintainer keeps working notes and instructions for coding agents alongside the code. The licence is MIT, so using the package inside a commercial app carries no copyleft obligation, and the pub.dev page at https://pub.dev/packages/badges is the documented home for the package.

What the package does not cover

The gaps are worth listing before you commit. The example app has folders for `android/`, `ios/` and `windows/` only, with no web, Linux or macOS platform directories, so the preview images give you no example of how the badge renders on those targets, even though the topics listed for the repository cover mobile and UI work generally. The README does not document accessibility behaviour for the badge, in particular whether its content is exposed to screen readers as a labelled count, and it says nothing about right to left layouts, where a badge on the trailing edge would need to swap sides. Semantics, localisation of the count text and theming against the app's own dark mode settings are all unaddressed in the documentation.

The version line is also thinner than it looks. The README pins `^4.0.0`, and the repository's release list shows a gap between 3.0.0-beta.1 from 2022 and 4.0.0 from 2026, so a codebase that has been living with an old beta will need the migration guide section rather than a version bump. The repository is not archived and the last push was on 2026-09-26, two days after the 4.0.0 tag, so the package is still being worked on, but the README itself was last updated around the 4.0.0 release.

Editorial conclusion

Adopt badges when you want a platform independent count marker with shape, gradient and animation control that the built-in widget does not offer, and when you can live with a namespace prefix or a hidden import. Skip it if your app already relies on the Badge widget in Flutter's own widget library, or if you need a package with a longer stable release history than one line. Verify first that the import style you choose matches the Material library your app uses, that the badge content stays inside a tap target when you set negative position offsets, and that the version pinned in pubspec.yaml is 4.0.0 rather than the 3.0.0-beta.1 line that older tutorials quote.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. yako-dev/flutter_badges on GitHub