PillSelector

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:

1import { PillSelector } from '@payloadcms/ui'

You can also import the component directly:

1import { PillSelector } from '@payloadcms/ui/elements/PillSelector'

Posts

Media

Users

Loading component example…

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

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.

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.

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.

Was this page helpful?