Badge is a label that indicates status or importance. Badges should provide quick recognition.
Some Text
Value
Status
Variant
Icon Name
Secondary
Max Value
Usage Guidelines
Do
Use badges to bring awareness to a specific element or feature
Use the colors to indicate urgency for scannability
Keep the language simple; this should be microcopy
Align the badge to the top of titles, or center align for base text
Choose a color style (default or secondary) for each kind of badge and stick with it. For example, all “needs interpreter” badges should share the same style
Don't
Use badges over photos or other colored media
Use multiple lines of text
Use different badge styles for the same kind of badge. For example, alternating between default and primary for “needs interpreter”
Accessibility
Screen readers can easily read badge elements, so no additional props are needed
Make sure that the text can demonstrate sentiment/urgency clearly enough to be understood without relying on color alone.
Props
Name
Type
Required
Description
color
For the "status" variant, whether the dot uses the bold (saturated) or
subtle (light) tone.
customBackgroundColor
string
When status is "custom", determines the badge's background color.
customBorderColor
string
When status is "custom", determines the badge's border color.
customIconColor
keyof TextTheme
When status is "custom", determines the badge's icon color
customIconName
IconName
When status is "custom", determines the badge's icon
customTextColor
string
When status is "custom", determines the badge's text color.
iconName
IconName
The name of the icon to display in the badge.
maxValue
number
The maximum value to display. Used for "numberOnly" variant to display "${maxValue}+" when
value is greater than max.
secondary
boolean
If true, the badge will have a secondary style.
status
The status of the badge. Determines its color and appearance.
testID
string
Root test id for the primary interactive element or container.
value
The text or number to display inside the badge.
variant
The variant of the badge. "status" renders a small colored dot (no text)
used to indicate an active/modified state.
Status
Documentation:
Figma:
Web:
iOS:
Android:
Examples
Badge vs SelectBadge
Badge vs SelectBadge — size comparison
Both should be 20px tall and visually aligned.
Info
Badge
Active
Success
Badge
Active
Warning
Badge
Active
Error
Badge
Active
Neutral
Badge
Active
Secondary variants
Secondary
Badge
Active
All Badge variants — height comparison
Text, iconOnly, and numberOnly should all be 20px tall.