Tag
Labels something with a status or category (Paid, Pending, Overdue). Not interactive: never make it look clickable.
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 tagAlso works with shadcn:
npx shadcn@latest add @ritla/tagOr 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 { Tag } from "@/components/ui/tag";<Tag tone="success" iconLeading={CheckCircleIcon}>Paid</Tag>Examples
Tones, emphasis and sizes
Five tones in subtle and solid emphasis, two sizes, an icon at the start or the end, or a flag with flag.
API reference
Tag
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Label: the word carries the status, not the color. |
tone | "neutral" | "brand" | "success" | "warning" | "danger" | "neutral" | Figma's Tone. |
emphasis | "subtle" | "solid" | "subtle" | Figma's Emphasis. |
size | "sm" | "md" | "md" | Figma's Size. |
iconLeading / iconTrailing | IconComponent | None | Figma's Style = Leading icon / Trailing icon. |
flag | string | None | Figma's Style = Flag: a country code (needs @ritla/flags). |
Usage guidelines
A tag is a label people read: a status or a category. How it differs from a chip, what its colors mean, how to write it, how it runs in Arabic, and the checks before handoff.
1. Tag or chip
Tags are labels: a status or a category people read, such as Paid or Overdue. Chips are controls: people press them. If pressing it should do something, it is a chip; if not, it is a tag and must never look pressable.
| Component | Use |
|---|---|
| Tag | A status or category that people read. Not interactive. |
| Suggestion chip | Quick picks people can tap: an amount, a reply. |
| Assist chip | A shortcut action related to the content, with an icon. |
| Filter chip | Turn a filter on or off; applies at once. |
| Input chip | A value people entered or picked, with a remove button. |
| Checkbox chip | Several options in a form, saved on submit. |
2. Tag colors mean something
Give each color one meaning across the product: Success for done or paid, Warning for waiting or needing attention, Error for failed or overdue, Brand for new or informational, Gray for neutral categories. Use Subtle in tables and lists; keep Solid for the one status that must stand out. The word always carries the meaning.
Subtle in lists, words first
Payment statuses in a transactions table.
Do
- Map each status to one color and keep it everywhere.
- Use Subtle tags in tables and lists.
- Write the status as a word; color only supports it.
Don't
- Use Solid for every tag in a table.
- Use a color for different meanings on different screens.
- Show a colored tag with no text.
3. Writing tags
A tag is one or two words from a fixed set: Paid, Pending, Overdue, Refunded. Use the same words everywhere a status appears, and never make a tag look like a button.
Do
- Use a fixed list of status words across the product.
- Keep tags to one or two words.
- Add an icon only when it adds meaning, the same icon for the same status.
Don't
- Write sentences inside a tag.
- Make a tag clickable, or give it hover states.
- Invent new words for the same status on different screens.
4. Arabic and RTL
Use the RTL variants: leading icons, flags and checks move to the right, trailing icons and remove buttons to the left, and a row of chips starts on the right. Write status words natively and keep them as short as in English.
Tags follow the Arabic layout
Payment statuses in Arabic.
Before handoff
- Tags for statuses, chips for anything pressed.
- Status words and their colors come from one fixed list.
- Arabic screens use the RTL variants.
Accessibility
ARIA
- Plain text, read with its surroundings; the icons and the flag are decorative.
- Don't rely on color alone.
Do
- Keep tags plain text, read in place.
Don't
- Give a tag a role or focus.
Arabic and RTL notes
Mirrors
- The leading icon and the flag sit at the inline start (the right), the trailing icon at the end.
Does not mirror
- Flags and status glyphs don't mirror.
- Numerals
- Numbers in a tag follow
numeralsthroughformatNumber. - Arabic typography
label-14(label-12at sm) Medium; the tag grows with the taller Arabic line.
Do
- Use the RTL variants for Arabic tags.
- Write status words natively: «مدفوع» for Paid, not a literal translation.
Don't
- English tags with Arabic labels.
- Translate status words literally when a shorter native word exists.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- 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)