# Badge

- Page: https://jiguang132.com/resources/astryx/docs/badge
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt