Badge
Badge highlights a status or category at a glance. Use it sparingly: only when a value represents a distinct state (Active, Failed) or a grouping tag (Engineering, Design). Most metadata (dates, durations, counts, descriptions) should be plain description text, not badges.
Installation
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
Requires React 19+, base CSS and a Theme provider. See Setup.
Badge
Badge highlights a status or category at a glance. Use it sparingly: only when a value represents a distinct state (Active, Failed) or a grouping tag (Engineering, Design). Most metadata (dates, durations, counts, descriptions) should be plain description text, not badges.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | 'neutral' | 'info' | 'success' | 'warning' | 'error' | 'blue' | 'cyan' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow' | 'neutral' | Visual style variant. Semantic variants (neutral, info, success, warning, error) use solid backgrounds. Non-semantic color variants use tinted backgrounds with colored text for categorization and tagging. |
| label | ReactNode | Badge text content. A badge is one line, so a label wider than the space available is cut with an ellipsis rather than escaping its container; a string or number label is also set as the badge's title so the full text stays reachable on hover. | |
| icon | ReactNode | Optional leading icon. |
Usage guidance
- Every status badge steals attention. Only badge states where the user needs to notice or act: errors, warnings, items requiring follow-up. If no action is needed, plain text is fine.
- Use success, warning, and error variants only for system status that demands attention: "Failed", "Degraded", "Action Required". These have bold solid backgrounds designed to stand out.
- Use color variants (blue, purple, teal, etc.) for category tags that group or classify items: team names, content types, priority levels.
- Keep labels to one or two words. If you need more detail, put it in surrounding text instead of the badge.
- Add an icon when it helps identify the badge type quickly, but always include a text label alongside it.
- Avoid: Apply a "success" badge to every healthy/active/normal item. If all rows show green "Active" badges, none stand out; the badge adds noise, not information. Show only the states that need user attention (errors, warnings, pending actions).
- Avoid: Use badges for metadata. Durations ("6h window"), counts ("12 trigger types"), dates, and descriptions are not statuses or categories; use description text (Text with type="supporting") instead.
- Avoid: Use semantic status variants (success, warning, error, info) for categories or informational content. These are visually loud and should only indicate system state.
- Avoid: Repeat the same badge in every row of a table or list. If the same value appears in most rows, it's not adding information; use plain text for common states and reserve badges for the exceptional ones.
- Avoid: Make badges clickable; they are read-only indicators. Use a button or link if the user needs to take action.
Theming API
{
"targets": [
{
"className": "astryx-badge",
"visualProps": [
"variant"
]
}
]
}
Anatomy
- Icon: An optional leading icon that helps identify the badge type at a glance.
- Label: The text or number shown inside the badge.
Examples
- Badge — Variants: All semantic and color badge variants in a single view. Use semantic variants for status and color variants for categories.
- Badge — Colors: Tag items with color-coded categories like teams, priorities, or topics. Use the 9 non-semantic color variants when you need to distinguish groups visually.
- Badge — Counts: Show a number inside a badge for notification counts, unread messages, or task totals. Use next to icons, nav items, or list labels.
- Badge — Status: Show the state of an item like Active, Pending, or Failed. Use in table rows, list items, or detail pages where users need to see status at a glance.