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.

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.

Token

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

{
  "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:

npm install @heroicons/react@2.2.0