Badge
A count (unread messages, pending approvals) or a dot for something new, inside tabs, navigation items, menus and rows. For status words, use a Tag.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add badgeAlso works with shadcn:
npx shadcn@latest add @ritla/badgeOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { Badge } from "@/components/ui/badge";<Badge tone="brand" count={3} label="unread messages" />Examples
Styles and sizes
Five colors, and on-brand for brand backgrounds; lg and md show the count and sm is a dot. Counts above max (99) show “99+”.
Dot sizes and the ring
At size="sm", dotSize picks 6, 8, 10 or 12px, and outline adds a ring in the tone's faint border, so the dot stands apart from what it sits on.
API reference
Badge
| Prop | Type | Default | Description |
|---|---|---|---|
tone | "neutral" | "brand" | "success" | "warning" | "danger" | "on-brand" | "neutral" | Figma's Tone. Danger only for urgent counts. |
size | "lg" | "md" | "sm" | "md" | Figma's Size; sm is a dot without a number. |
count | number | string | None | Figma's Count; a number is formatted in the numeral system. |
max | number | 99 | Above it shows “99+”. |
label | ReactNode | None | Hidden text read after the count (“unread messages”); a dot without one reads “New”. |
numerals | "latn" | "arab" | None | Default: from RitlaProvider. |
dotSize | "xs" | "sm" | "md" | "lg" | "xs" | The _Dot Size at size="sm": 6, 8, 10 or 12px. |
outline | boolean | false | The _Dot Outline: a ring in the tone's faint border around the dot. |
Usage guidelines
A badge is a count or a dot attached to something else. Badge, Tag or Chip, colors by meaning, counts and dots, its place and digits in Arabic, and the checks before handoff.
1. Badge, Tag or Chip
A badge is a count or a dot attached to something else. Words that describe a state (Active, Pending, Overdue) are Tags; things people pick or remove are Chips.
| You need to | Use | Why |
|---|---|---|
| Show how many: 3 pending approvals | Badge, md or lg | A number people act on. |
| Show that something is new | Badge, sm (dot) | Presence matters, not the number. |
| Describe a state: Active, Overdue | Tag | A word, not a count. |
| Show a filter or a choice people can remove | Chip | It can be pressed. |
| Show a person's availability | Avatar status | It belongs to the person. |
2. Colors by meaning
Pick the color for what the count means, not to decorate. Most counts are Gray or Brand; Error is kept for what is urgent or failing, so it still stands out.
| Style | Meaning |
|---|---|
| Gray | Neutral totals: 12 documents, 48 transactions. |
| Brand | Unread or new items that invite a look. |
| Success | Positive counts: 3 payments received. |
| Warning | Needs attention soon: 2 cards expiring. |
| Error | Urgent or failed: 1 payment failed. |
| On Brand | Any count on a brand-colored surface. |
Do
- Use Gray or Brand for most counts.
- Keep Error for urgent or failed items.
- Use On Brand on brand surfaces.
Don't
- Make every badge Error to get attention.
- Use color alone to explain what the count means.
3. Counts and dots
Show a count when the number changes what people do, and a dot when only “something new” matters. Cap long counts at 99+. Hide the badge at zero, and clear it once people have seen what it counted. In code a hidden label says what is counted: “3 unread messages”.
Cap long counts
A Requests tab with many items.
Do
- Cap counts at 99+.
- Hide the badge when the count is zero.
- Clear it when people open what it counts.
- Pass a label for screen readers: “unread messages”.
Don't
- Show exact large numbers like 1,284 in a badge.
- Show 0.
- Keep a badge after people have seen everything.
4. Arabic and numerals
The badge sits after its label, at the inline end: to the left of an Arabic label. Counts follow the numerals setting like every other number in the product: 3 or ٣. Use the same digits in the badge and the label around it.
The badge follows the label
A Requests item in Arabic.
Before handoff
- Counts where the number matters, dots where only “new” matters.
- Colors chosen by meaning, Error kept for urgent.
- Cap, zero and clearing behavior are noted.
- Hidden labels for what each badge counts.
Accessibility
ARIA
- The count is text read with its meaning through
label(3 unread messages); color alone never carries the meaning. - A dot has a hidden name, “New” by default in the page language.
Do
- Say what the count counts in hidden text: “3 pending approvals”.
- A dot reads “New” in the page language.
- Keep dots at 3:1 against the page; code uses the icon colors.
Don't
- Rely on color to tell urgent from normal.
- Announce a count with no context: “3”.
Arabic and RTL notes
Mirrors
- The badge follows its place in the row: at the inline end (the left) in Arabic.
Does not mirror
- “99+” keeps its order: the number is isolated LTR.
- Numerals
- The count follows
numeralsorRitlaProvider(Western by default), so it matches the amounts elsewhere on the screen. - Arabic typography
label-12Medium; the badge grows with the taller Arabic line.
Do
- Put the badge at the inline end of the label, to its left in Arabic.
- Follow the product's numerals setting for counts.
- Write 99+ in the same digits as the rest of the screen.
Don't
- Put the badge before the Arabic label.
- Mix Western and Arabic-Indic digits on one screen.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Unisolated bidi hazards: phones, emails, Latin tokens inside Arabic text
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)