Skip to content

Badge

Get Ritla UI

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

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add badge

    Also works with shadcn: npx shadcn@latest add @ritla/badge

  2. Or 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

badge.tsx
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+”.

EnglishMirroredArabic
LTR →

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.

EnglishMirroredArabic
LTR →

API reference

Badge

PropTypeDefaultDescription
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.
countnumber | stringNoneFigma's Count; a number is formatted in the numeral system.
maxnumber99Above it shows “99+”.
labelReactNodeNoneHidden text read after the count (“unread messages”); a dot without one reads “New”.
numerals"latn" | "arab"NoneDefault: from RitlaProvider.
dotSize"xs" | "sm" | "md" | "lg""xs"The _Dot Size at size="sm": 6, 8, 10 or 12px.
outlinebooleanfalseThe _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 toUseWhy
Show how many: 3 pending approvalsBadge, md or lgA number people act on.
Show that something is newBadge, sm (dot)Presence matters, not the number.
Describe a state: Active, OverdueTagA word, not a count.
Show a filter or a choice people can removeChipIt can be pressed.
Show a person's availabilityAvatar statusIt 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.

StyleMeaning
GrayNeutral totals: 12 documents, 48 transactions.
BrandUnread or new items that invite a look.
SuccessPositive counts: 3 payments received.
WarningNeeds attention soon: 2 cards expiring.
ErrorUrgent or failed: 1 payment failed.
On BrandAny 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: Capped at 99+Short, even, and still says “a lot”.
Don't: The exact numberA four-digit badge crowds the label and nobody reads the exact figure.

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.

Do: After the labelThe count sits to the left of الطلبات, where the Arabic line ends.
Don't: Before the labelThe count comes first and reads as part of a different item.

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 numerals or RitlaProvider (Western by default), so it matches the amounts elsewhere on the screen.
Arabic typography
label-12 Medium; 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.

  • R021Unisolated bidi hazards: phones, emails, Latin tokens inside Arabic text
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space
  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)