# Token

## Usage

`Token` is an interactive chip. It can be removed, clicked, or used as a link, for a selected value or a filter. `Badge` is a static status or count marker.

Typeahead, Multi Selector, and Tokenizer use `Token` internally, and a chat composer can use it for an attachment or a mention.

`removable` shows a focusable remove button. Click, `Backspace`, and `Delete` all emit `remove`. `disabled` ignores that action. `#icon` sits before the text and is the place for a type icon.

`href` renders a link. When a remove button is also present, the link and the button are siblings, so the button is not nested inside the link.

```vue
<script setup lang="ts">
import { Token } from '@astryx-vue/core/Token'
</script>

<template>
  <Token label="Design review" color="blue" removable>
    <template #icon>
      <span aria-hidden="true">#</span>
    </template>
  </Token>
</template>
```

The remove button’s accessible name defaults to `Remove Design review`. `provideAstryxLocale('zh-CN')` switches it to Chinese.

## Best Practices

| Guideline | Practice |
| --- | --- |
| Do | Turn on `removable` when the person can dismiss the chip, and update your list in `remove`. |
| Do | Use `#icon` for the type. Keep the icon out of `label`. |
| Don't | Use Token for success or warning status. Use `Badge` for that. |

### 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 labelHidden is true.
- **End content**: Trailing content after the label, like a count badge or status dot.
- **Remove button**: An X button that appears when removable is set. Activating it emits remove.

## Examples

### Clickable

Interactive tokens that respond to clicks. Use for toggleable filters or tokens that open a detail view.

```vue
<script setup lang="ts">
import { Token } from '@astryx-vue/core/Token'
</script>

<template>
  <div class="demo-row">
    <Token label="Bug" color="red" @click="() => {}" />
    <Token label="Feature" color="blue" @click="() => {}" />
    <Token label="Enhancement" color="green" @click="() => {}" />
    <Token label="Documentation" color="gray" @click="() => {}" />
  </div>
</template>

<style scoped>
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}
</style>
```

### Colors

All 11 color variants in default and disabled states.

```vue
<script setup lang="ts">
import type { TokenColor } from '@astryx-vue/core/Token'
import { Token } from '@astryx-vue/core/Token'

const colors: { color: TokenColor, label: string }[] = [
  { color: 'default', label: 'Default' },
  { color: 'red', label: 'Red' },
  { color: 'orange', label: 'Orange' },
  { color: 'yellow', label: 'Yellow' },
  { color: 'green', label: 'Green' },
  { color: 'teal', label: 'Teal' },
  { color: 'cyan', label: 'Cyan' },
  { color: 'blue', label: 'Blue' },
  { color: 'purple', label: 'Purple' },
  { color: 'pink', label: 'Pink' },
  { color: 'gray', label: 'Gray' },
]
</script>

<template>
  <div class="demo-stack">
    <p class="demo-caption">
      {{ 'Default' }}
    </p>
    <div class="demo-row">
      <Token v-for="item in colors" :key="item.color" :label="item.label" :color="item.color" />
    </div>
    <p class="demo-caption">
      {{ 'Disabled' }}
    </p>
    <div class="demo-row">
      <Token v-for="item in colors" :key="`disabled-${item.color}`" :label="item.label" :color="item.color" disabled />
    </div>
  </div>
</template>

<style scoped>
.demo-stack {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
  max-width: 25rem;
}
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 0.25rem;
}
.demo-caption {
  margin: 0.5rem 0 0;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}
.demo-caption:first-child {
  margin-top: 0;
}
</style>
```

### End Content

Tokens with trailing content like a count badge or status indicator.

```vue
<script setup lang="ts">
import { Badge } from '@astryx-vue/core/Badge'
import { Token } from '@astryx-vue/core/Token'
</script>

<template>
  <div class="demo-row">
    <Token label="Inbox" color="blue">
      <template #end>
        <Badge variant="info">
          12
        </Badge>
      </template>
    </Token>
    <Token label="Reviews" color="purple">
      <template #end>
        <Badge variant="purple">
          3
        </Badge>
      </template>
    </Token>
    <Token label="Resolved" color="green">
      <template #end>
        <Badge variant="success">
          {{ 'Done' }}
        </Badge>
      </template>
    </Token>
  </div>
</template>

<style scoped>
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
  align-items: center;
}
</style>
```

### Icon

Tokens with a leading icon that identifies the entity type.

```vue
<script setup lang="ts">
import { Token } from '@astryx-vue/core/Token'
</script>

<template>
  <div class="demo-stack">
    <p class="demo-caption">
      {{ 'Icons identify the token category' }}
    </p>
    <div class="demo-row">
      <Token label="Sarah Chen" color="blue">
        <template #icon>
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" d="M15.75 6a3.75 3.75 0 1 1-7.5 0 3.75 3.75 0 0 1 7.5 0ZM4.501 20.118a7.5 7.5 0 0 1 14.998 0A17.933 17.933 0 0 1 12 21.75c-2.676 0-5.216-.584-7.499-1.632Z" /></svg>
        </template>
      </Token>
      <Token label="Featured" color="yellow">
        <template #icon>
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" d="M11.48 3.499a.562.562 0 0 1 1.04 0l2.125 5.111a.563.563 0 0 0 .475.345l5.518.442c.499.04.701.663.321.988l-4.204 3.602a.563.563 0 0 0-.182.557l1.285 5.385a.562.562 0 0 1-.84.61l-4.725-2.885a.562.562 0 0 0-.586 0L6.982 20.54a.562.562 0 0 1-.84-.61l1.285-5.386a.562.562 0 0 0-.182-.557l-4.204-3.602a.562.562 0 0 1 .321-.988l5.518-.442a.563.563 0 0 0 .475-.345L11.48 3.5Z" /></svg>
        </template>
      </Token>
      <Token label="Design" color="purple">
        <template #icon>
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" d="M9.568 3H5.25A2.25 2.25 0 0 0 3 5.25v4.318c0 .597.237 1.17.659 1.591l9.581 9.581c.699.699 1.78.872 2.607.33a18.095 18.095 0 0 0 5.223-5.223c.542-.827.369-1.908-.33-2.607L11.16 3.66A2.25 2.25 0 0 0 9.568 3Z" /><path stroke-linecap="round" stroke-linejoin="round" d="M6 6h.008v.008H6V6Z" /></svg>
        </template>
      </Token>
      <Token label="Verified" color="green">
        <template #icon>
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75 11.25 15 15 9.75m-3-7.036A11.959 11.959 0 0 1 3.598 6 11.99 11.99 0 0 0 3 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285Z" /></svg>
        </template>
      </Token>
    </div>
  </div>
</template>

<style scoped>
.demo-stack {
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
}
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
  align-items: center;
}
.demo-caption {
  margin: 0;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}
.demo-row :deep(svg) {
  width: 0.875rem;
  height: 0.875rem;
}
</style>
```

### Removable

Tokens with a dismiss button for selections the user can undo.

```vue
<script setup lang="ts">
import { Token } from '@astryx-vue/core/Token'
</script>

<template>
  <div class="demo-container">
    <p class="demo-caption">
      {{ 'Active filters' }}
    </p>
    <div class="demo-row">
      <Token label="Status: Open" color="green" removable />
      <Token label="Priority: High" color="red" removable />
      <Token label="Team: Design" color="purple" removable />
    </div>
    <p class="demo-caption">
      {{ 'Selected recipients' }}
    </p>
    <div class="demo-row">
      <Token label="Sarah Chen" color="blue" removable />
      <Token label="Alex Rivera" color="blue" removable />
      <Token label="Jordan Lee" color="blue" removable />
    </div>
  </div>
</template>

<style scoped>
.demo-container {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}
.demo-caption {
  margin: 0.5rem 0 0;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}
.demo-caption:first-child {
  margin-top: 0;
}
</style>
```

## Token Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | Required | Text, also the accessible name. |
| `color` | `'default' \| 'gray' \| 'blue' \| 'cyan' \| 'teal' \| 'green' \| 'yellow' \| 'orange' \| 'red' \| 'pink' \| 'purple'` | `'default'` | Color. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size. |
| `removable` | `boolean` | `false` | Show a focusable remove button. |
| `disabled` | `boolean` | `false` | Disable the token. The remove button stops responding. |
| `href` | `string` | — | Render a link. With a remove button, the link and button are siblings. |
| `description` | `string` | — | Extra text for assistive technology. |
| `isLabelHidden` | `boolean` | `false` | Hide the text visually while keeping the accessible name. `labelHidden` is the older name; either one hides it. |

## Token Emits

| Name | Parameters | Description |
| --- | --- | --- |
| `remove` | `event: Event` | Click the remove button, or press Backspace / Delete on the token. |

## Token Slots

| Name | Parameters | Description |
| --- | --- | --- |
| `icon` | — | Icon before the text. |
| `end` | — | Content after the text and before the remove button. Also available as `endContent`. |