# PillSelector

Source: https://payloadcms.com/docs/beta/ui-components/pill-selector

The `PillSelector` component displays a wrapping list of options that can be selected, deselected, and optionally reordered.

## Import

Inside a Payload Admin Panel Custom Component:

```tsx
import { PillSelector } from '@payloadcms/ui'
```

You can also import the component directly:

```tsx
import { PillSelector } from '@payloadcms/ui/elements/PillSelector'
```

## Interactive example

**Implementation**

```tsx
const [pills, setPills] = useState([
  { name: 'Posts', selected: true },
  { name: 'Media', selected: false },
  { name: 'Users', selected: true },
])

<PillSelector
  onClick={({ pill }) => {
    setPills((current) =>
      current.map((item) =>
        item.name === pill.name
          ? { ...item, selected: !item.selected }
          : item,
      ),
    )
  }}
  pills={pills}
/>
```

**Styling**

Override tokens on the selector surface and its selected Chips to customize this group without changing the same colors throughout the Admin Panel.

```css
@layer payload {
  .pill-selector {
    --color-bg-secondary: #f7f5ff;
    --spacer-4: 1.25rem;
  }

  .pill-selector .chip--selected {
    --color-bg-brand-tertiary: #e8e4ff;
    --color-border-brand: #6d5dfc;
  }
}
```

- `--color-bg-secondary`: PillSelector surface color.
- `--color-bg-brand-tertiary`: Selected Chip background.
- `--color-border-brand`: Selected Chip border.
- `--spacer-4`: PillSelector padding.

The component does not manage selection state. Update the `pills` array in `onClick` and pass the new array back to the component.

## Pill shape

Each item in `pills` accepts:

| Property      | Type        | Description                                  |
| ------------- | ----------- | -------------------------------------------- |
| `name` \*     | `string`    | Stable value and default visible label.      |
| `selected` \* | `boolean`   | Whether the option is currently selected.    |
| `Label`       | `ReactNode` | Replaces the visible label.                  |
| `key`         | `string`    | Overrides the React key used for the option. |

_\* An asterisk denotes that a property is required._

## Accessibility

- Give each option a short, unique `name`; Payload uses it as the Chip's accessible label.
- Do not communicate selection by color alone. Selected items replace the plus icon with a remove icon.
- When enabling reordering, provide another way to understand or change the order when drag-and-drop is unavailable.

## Common props

These are the props most commonly used with this component. See its exported types in `@payloadcms/ui` for the complete list.

| Prop        | Type                                                      | Default | Description                                |
| ----------- | --------------------------------------------------------- | ------- | ------------------------------------------ |
| `pills` \*  | `SelectablePill[]`                                        | —       | Options displayed by the selector.         |
| `onClick`   | `({ pill }) => Promise<void> \| void`                     | —       | Called when an option is activated.        |
| `draggable` | `{ onDragEnd: ({ moveFromIndex, moveToIndex }) => void }` | —       | Enables reordering and handles the result. |

_\* An asterisk denotes that a prop is required._