Token is a small, inline element for representing discrete pieces of associated data, like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.
ts
| Guidance | Practices |
|---|---|
| Do | Use color to distinguish categories (for example, green for "Active", red for "Blocked", blue for "In Review") so users can scan status at a glance. |
| Do | Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values. |
| Do | Add a leading icon when it helps identify the token type faster, like a person icon for user tokens or a tag icon for labels. |
| Do | Keep labels short: one to three words. Tokens truncate with ellipsis when the text overflows. |
| Don't | Don't use tokens for primary actions or navigation; use Button or Link instead. Tokens are for displaying metadata, not triggering workflows. |
| Don't | Don't hide the label unless the icon alone is universally understood. A color dot without text is ambiguous. |
| Don't | Don't mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable. |
Interactive tokens that respond to clicks. Use for toggleable filters or tokens that open a detail view when selected.
All 11 color variants in default and disabled states. Use color to categorize entities or convey status at a glance.
Tokens with trailing content like a count badge or status indicator after the label. Use for notification counts, item quantities, or compact status info.
Tokens with a leading icon that identifies the entity type. Use when the icon helps users recognize the token category faster, like a user icon for people or a tag icon for labels.
Tokens with a dismiss button for selections the user can undo. Use in multi-select fields, active filters, or any list of user-chosen items.