XDS — Design System

XDSToken@xds/core · Token

Preview coming soon

Usage

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.

Best practices

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.

Anatomy

Element		Description
Icon		A leading icon that identifies the token type, like a user avatar or category symbol.
Label	required	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.

Import

ts
import {XDSToken} from '@xds/core/Token'

Props

Prop	Type	Description
labelrequired	string	Text label displayed inside the token.
size	'sm' \| 'md' (default: 'md')	The size of the token.
color	'default' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'cyan' \| 'blue' \| 'purple' \| 'pink' \| 'gray' (default: 'default')	Color variant of the token.
icon	ReactNode	Optional icon rendered before the label.
isDisabled	boolean (default: 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.
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 (default: 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={{}}.

Examples

Common configurations, variations, and states.

Token — ClickableInteractive tokens that respond to clicks. Use for toggleable filters or tokens that open a detail view when selected.

tsx
'use client';
import {XDSToken} from '@xds/core/Token';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function TokenClickable() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSText type="supporting" color="secondary">
        Click a token to view details
      </XDSText>
      <XDSStack direction="horizontal" gap={2} wrap="wrap">
        <XDSToken label="Bug" color="red" onClick={() => {}} />
        <XDSToken label="Feature" color="blue" onClick={() => {}} />
        <XDSToken label="Enhancement" color="green" onClick={() => {}} />
        <XDSToken label="Documentation" color="gray" onClick={() => {}} />
      </XDSStack>
    </XDSStack>
  );
}

Token — ColorsAll 11 color variants in default and disabled states. Use color to categorize entities or convey status at a glance.

tsx
'use client';
import {XDSToken} from '@xds/core/Token';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
const COLORS = [
  {color: 'default' as const, label: 'Default'},
  {color: 'red' as const, label: 'Red'},
  {color: 'orange' as const, label: 'Orange'},
  {color: 'yellow' as const, label: 'Yellow'},
  {color: 'green' as const, label: 'Green'},
  {color: 'teal' as const, label: 'Teal'},
  {color: 'cyan' as const, label: 'Cyan'},
  {color: 'blue' as const, label: 'Blue'},
  {color: 'purple' as const, label: 'Purple'},
  {color: 'pink' as const, label: 'Pink'},
  {color: 'gray' as const, label: 'Gray'},
];
export default function TokenColors() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Default
        </XDSText>
        <XDSStack direction="horizontal" gap={2} wrap="wrap">
          {COLORS.map(({color, label}) => (
            <XDSToken key={color} label={label} color={color} />
          ))}
        </XDSStack>
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Disabled
        </XDSText>
        <XDSStack direction="horizontal" gap={2} wrap="wrap">
          {COLORS.map(({color, label}) => (
            <XDSToken key={color} label={label} color={color} isDisabled />
          ))}
        </XDSStack>
      </XDSStack>
    </XDSStack>
  );
}

Token — End ContentTokens with trailing content like a count badge or status indicator after the label. Use for notification counts, item quantities, or compact status info.

tsx
'use client';
import {XDSToken} from '@xds/core/Token';
import {XDSBadge} from '@xds/core/Badge';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function TokenEndContent() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSText type="supporting" color="secondary">
        Trailing badges for counts or status
      </XDSText>
      <XDSStack direction="horizontal" gap={2} wrap="wrap">
        <XDSToken
          label="Inbox"
          color="blue"
          endContent={<XDSBadge variant="info" label={12} />}
        />
        <XDSToken
          label="Reviews"
          color="purple"
          endContent={<XDSBadge variant="purple" label={3} />}
        />
        <XDSToken
          label="Resolved"
          color="green"
          endContent={<XDSBadge variant="success" label="Done" />}
        />
      </XDSStack>
    </XDSStack>
  );
}

Token — IconTokens 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.

tsx
'use client';
import {XDSToken} from '@xds/core/Token';
import {XDSIcon} from '@xds/core/Icon';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
import {
  StarIcon,
  TagIcon,
  UserIcon,
  ShieldCheckIcon,
} from '@heroicons/react/24/outline';
export default function TokenIcon() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSText type="supporting" color="secondary">
        Icons identify the token category
      </XDSText>
      <XDSStack direction="horizontal" gap={2} wrap="wrap">
        <XDSToken
          label="Sarah Chen"
          color="blue"
          icon={<XDSIcon icon={UserIcon} size="sm" color="inherit" />}
        />
        <XDSToken
          label="Featured"
          color="yellow"
          icon={<XDSIcon icon={StarIcon} size="sm" color="inherit" />}
        />
        <XDSToken
          label="Design"
          color="purple"
          icon={<XDSIcon icon={TagIcon} size="sm" color="inherit" />}
        />
        <XDSToken
          label="Verified"
          color="green"
          icon={<XDSIcon icon={ShieldCheckIcon} size="sm" color="inherit" />}
        />
      </XDSStack>
    </XDSStack>
  );
}

Token — RemovableTokens with a dismiss button for selections the user can undo. Use in multi-select fields, active filters, or any list of user-chosen items.

tsx
'use client';
import {XDSToken} from '@xds/core/Token';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function TokenRemovable() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Active filters
        </XDSText>
        <XDSStack direction="horizontal" gap={2} wrap="wrap">
          <XDSToken label="Status: Open" color="green" onRemove={() => {}} />
          <XDSToken label="Priority: High" color="red" onRemove={() => {}} />
          <XDSToken label="Team: Design" color="purple" onRemove={() => {}} />
        </XDSStack>
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Selected recipients
        </XDSText>
        <XDSStack direction="horizontal" gap={2} wrap="wrap">
          <XDSToken label="Sarah Chen" color="blue" onRemove={() => {}} />
          <XDSToken label="Alex Rivera" color="blue" onRemove={() => {}} />
          <XDSToken label="Jordan Lee" color="blue" onRemove={() => {}} />
        </XDSStack>
      </XDSStack>
    </XDSStack>
  );
}

Showcase source

tsx
'use client';
import {XDSToken} from '@xds/core/Token';
import {XDSIcon} from '@xds/core/Icon';
import {XDSStack} from '@xds/core/Layout';
import {TagIcon} from '@heroicons/react/24/outline';
export default function TokenShowcase() {
  return (
    <XDSStack direction="horizontal" gap={2} vAlign="center">
      <XDSToken label="Default" />
      <XDSToken label="Removable" color="blue" onRemove={() => {}} />
      <XDSToken
        label="Design"
        color="purple"
        icon={<XDSIcon icon={TagIcon} size="sm" color="inherit" />}
      />
    </XDSStack>
  );
}