# Token

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

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.

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

## Token

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.

| Prop | Type | Default | Description |
|---|---|---|---|
| label * | string |  | Text label displayed inside the token. |
| size | 'sm' \| 'md' \| 'lg' | 'md' | The size of the token. |
| color | 'default' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'cyan' \| 'blue' \| 'purple' \| 'pink' \| 'gray' | 'default' | Color variant of the token. |
| icon | ReactNode |  | Optional icon rendered before the label. |
| isDisabled | boolean | false | Whether the token is disabled; reduces opacity and blocks interactions. |
| onRemove | (e: React.MouseEvent) => void |  | Callback fired when the remove button is clicked. When provided, an X button is rendered inside the token. |
| onClick | (e: React.MouseEvent) => void |  | Click handler. When provided, the token renders as a <span> container with an invisible <button> inside for accessibility. |
| href | string |  | Link URL. When provided, the token renders as an <a> element. The destination follows the shared navigation rule described on the Link `href` prop. |
| description | string |  | Accessible description applied via aria-description on the root element. |
| endContent | ReactNode |  | Content rendered after the label and before the remove button. |
| isLabelHidden | boolean | false | Visually hides the label using a screen-reader-only clip technique; the label remains accessible. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |

### Usage guidance

- 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.
- Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values.
- 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.
- Keep labels short: one to three words. Tokens truncate with ellipsis when the text overflows.
- Avoid: Don't use tokens for primary actions or navigation; use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.
- Avoid: Don't hide the label unless the icon alone is universally understood. A color dot without text is ambiguous.
- Avoid: Don't mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-token",
      "visualProps": [
        "color",
        "size"
      ]
    }
  ]
}
```

### Anatomy

- **Icon**: A leading icon that identifies the token type, like a user avatar or category symbol.
- **Label**: The visible text. Also used as the accessible name when isLabelHidden is true.
- **End content**: Trailing content after the label, like a count badge or status dot.
- **Remove button**: An X button that appears when onRemove is provided, letting users dismiss the token.


## Examples

- Token: 
- Token — Clickable: Interactive tokens that respond to clicks. Use for toggleable filters or tokens that open a detail view when selected.
- Token — Colors: All 11 color variants in default and disabled states. Use color to categorize entities or convey status at a glance.
- Token — End Content: Tokens with trailing content like a count badge or status indicator after the label. Use for notification counts, item quantities, or compact status info.
- Token — Icon: 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.
- Token — Removable: 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.

## Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

```bash
npm install @heroicons/react@2.2.0
```

---

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