# Context Pill

A removable chip for what the prompt refers to: a file, a person, a channel or a link.

- Category: AI & Agents
- Page: https://wunderui.com/components/context-pill
- Tier: Core and Pro

## Install

Context Pill ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ContextPill } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ContextPill } from "@wunderui/react"

export function Attached({ onRemove }: { onRemove: () => void }) {
  return <ContextPill kind="file" label="tabs.tsx" onRemove={onRemove} />
}
```

Expected result: You see a small pill with a file icon, tabs.tsx and a close button. Pressing the button calls the remove handler, and without a handler the button is gone.

## When to use

### Use Context Pill for

- The things a prompt refers to: files, people, channels and links, shown above the field
- Context that the reader can take out again with one button
- Context that the system attached and that stays, as a pill without a button

### Use something else

- [Mention Picker](https://wunderui.com/components/mention-picker) for the list the reader picks from after typing an at sign
- [Chat Attachment](https://wunderui.com/components/chat-attachment) for a file with its size and upload state
- [Badge](https://wunderui.com/components/badge) for a static label that is not removable context
- [Avatar Group](https://wunderui.com/components/avatar-group) for several people as a row of overlapping avatars

## Keyboard

The pill takes no focus and handles no key. Its only control is the native remove button, so the browser handles focus and activation.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous remove button, in the order of the pills, and on to the next control. Pills without `onRemove` are skipped. |
| `Enter` or `Space` | On a remove button: calls `onRemove`. The button leaves the page, so move focus to the field or to the next remove button yourself. |

The pill ignores Backspace and Delete. A composer can remove the last pill on Backspace in an empty field, as the Examples tab does.

## Behavior

What the pill does with its label, avatar, button, assistive technology and motion.

- **Width:** The pill takes the width of its content and never grows past its row. Several pills sit side by side in a flex row, and the parent decides whether they wrap, scroll or collapse.
- **Long labels:** A long label is cut off with an ellipsis on one line, but the full text stays for assistive technology. In a scrolling row, stop each pill from shrinking or the labels get squeezed.
- **Avatar:** A person pill shows a 16 px avatar with the initials as given, or the first two letters of the label in capitals (NO for Nora Lindgren). The colour defaults to orange.
- **Removing:** The button only calls the remove handler. The pill is not hidden or animated by the component, so remove it from your state and it leaves on the next render.
- **Hover and focus:** The button goes from tertiary to the foreground colour on hover. Focus shows the indigo border with the 2 px ring.
- **Target size:** The remove button is 16 px square, smaller than the 24 px of WCAG 2.5.8. Keep pills at least 6 px apart and offer a second way to remove, such as Backspace in the field.
- **Assistive technology:** The pill reads as its label, and the button is named Remove plus the label. Nothing is announced when a pill is added or removed, so say it in a status line.
- **Failure:** The pill has no error or loading state. If removing can fail, keep the pill and show the error next to the row.
- **Motion:** The pill does not animate. A pill that enters or leaves in your layout can fade on opacity only, with the fast duration.
- **Reduced motion:** Nothing in the pill depends on reduced motion, because it has no motion of its own.

## Anatomy

- `ContextPill`: A small inline pill with a thin border, a subtle fill and 12 px medium text. It takes the width of its label, has no role and cannot be focused, apart from its remove button.
- `Leading mark`: A person gets a 16 px avatar with initials (the first two letters of the label by default) in a colour that defaults to orange. A file, channel or link gets a 14 px icon.
- `Label`: The label sits on one line. When the row is narrower than the pill, the text is cut with an ellipsis and never wraps.
- `Remove button`: A native button named Remove plus the label, with a 12 px close icon. It appears only when a remove handler is given, is 16 px square and sits in the tab order.

## Best practices

### When to use

- Use Context Pill for what a prompt refers to: a file, person, channel or link. For a file with size and upload state use Chat Attachment; for the list to pick from, Mention Picker.

### Do

- Set the kind to what is referenced. For a person, pass initials and colour so the avatar matches the one used elsewhere.
- Add a remove handler for context the reader added. Leave it out for context the system attached, such as the open file, so people see it stays.
- Put the pills in a group with a name such as Context, and announce changes in a status line like Removed tabs.tsx. The pill itself is silent.
- Move focus when a pill is removed. The button that had focus is gone, so send focus to the field or the next remove button.
- Decide what happens with many pills: wrap, scroll on one line or show a few plus a button for the rest. Without a rule they squeeze each other and labels get cut off.

### Don't

- Don't put a path or a sentence in the label: it is cut off on one line and there is no tooltip for the rest. Use the file or channel name.
- Don't use a pill as a button. It has no click action, so put a link or button beside it to open the item.

## API reference

### ContextPill

| Prop | Type | Default | Description |
|---|---|---|---|
| kind* | "link" \| "file" \| "person" \| "channel" |  | What is referenced: `file`, `person`, `channel` or `link`. Picks the leading mark: an avatar for `person`, a file, hash or link icon for the others. Also set as `data-kind`. |
| label* | string |  | The name, on one line: `tabs.tsx`, `Nora Lindgren`, `#finance-ops`. Also the accessible name of the remove button (`Remove <label>`). |
| className | string |  | Extra classes for the pill, for example `shrink-0` in a row that scrolls or a margin. |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" \| "grey" | "orange" | The avatar colour of a `person` pill: `indigo`, `blue`, `purple`, `pink`, `red`, `orange`, `yellow`, `green`, `alternative` or `grey`. Default `orange`. Ignored for the other kinds. |
| initials | string |  | The letters in the avatar of a `person` pill. Default: the first two letters of `label`, in capitals. Ignored for the other kinds. |
| onRemove | () => void |  | Called when the remove button is pressed. Without it there is no button, which is how you mark context that must stay. |

## Examples

### Label: short, long, cut off by the width of its row

### Person: initials you set, initials from the label, other colours

### One chip family with the record chip

## In context

### Context row: add, remove, Backspace

Pills sit above the field and Add context under it. Tab reaches a pill's remove button and Enter removes it, and Backspace in the empty field removes the last pill and returns focus to the field.

### Many pills: wrap, scroll, collapse

Twelve pills in a 420 px field. Wrap keeps every pill in sight, scroll keeps one line, and collapse shows the first four and a button for the rest.

### Locked and removable: the run keeps its file

A pill without a remove handler has no button. The open file is attached by the run and stays, while people, files and channels the reader added can be removed.

## For AI agents

`get_component("context-pill")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
