Usage
A status badge is a small filled label that reports the state of the thing it sits next to. It carries one word or two, it isn’t tappable, and it changes only when the underlying state changes.
- Keep it to one word where you can, two at most.
- Pair it with text that names the item, so the badge is never the only thing carrying the meaning.
- Show one badge per item.
- Keep it current. If the state changes while the screen is open, the badge changes with it.
- Use as a control. A status badge is not tappable. If it should filter or select, use a chip.
- Use for information that isn’t a state. A time, a count, a score, or a category belongs in the text, not in a badge.
- Use to count things or mark unread activity on an icon (use a badge).
- Badge every item in a list.
- Stack badges on one item.
Design properties
| Property | Values | Default |
|---|---|---|
| Type Variant | Info | Success | Error | Info |
Types
The three types are named for feedback (Info, Success, Error) but the states they carry are often about the world rather than about the app. A late flight is not a Firefox error. Read past the names and pick by asking: is this good news, bad news, or neither?
|
The state is… |
Type |
|---|---|
|
The good outcome, or on track |
Success |
|
Worse for the person |
Error |
|
Ongoing, neutral, or none of the above |
Info |
Info
The neutral, default state. Use it for ongoing or informational statuses, such as Syncing or New. Most badges should use Info.
Success
A positive or on-track outcome. Use it for statuses such as Protected or Up to date, rather than something still in progress.
Error
A negative outcome, such as Blocked or Cancelled. Since there may be nothing the person can do, avoid wording the label as if action is required.
Behavior and interaction
Behavior
- The badge is not a control. It has no pressed, hover, focus, or disabled state. If the row it sits in is tappable, the row is the target and the badge is part of it.
- It doesn’t animate, pulse, or count down. A badge reading Live is still just a label.
- When the state changes, swap the type and the label together. A badge that keeps its old color with new text reads as a bug.
- Where the state comes from live data, stale is worse than absent. If it can’t be confirmed, drop the badge and keep the rest of the row rather than showing a last known value.
- Don’t show a loading or skeleton badge while data is in flight.
- For New badges, reference Beta and New duration rules for guidance on how long the badge should appear.
Positioning
- Place the badge on the same line as the thing it describes, and after it, so the two are read together.
- The badge hugs its label and doesn’t truncate. Give the row enough space for the longest translated string, and let the surrounding text truncate instead.
- Don’t place a badge on its own line or centered on a screen.
- Check the badge at the narrowest supported width with the longest string before signing off, especially in dense layouts.
Related components
Changelog
|
Date |
Version |
Notes |
|---|---|---|
|
Aug 25, 2026 |
1.0.0 |
Initial draft of guidance |