Formsstable
Multi-Select
A searchable multi-select component with badges for displaying selected items, perfect for forms and complex filters.
Installation
Install the component directly into your project using the Pittaya CLI.
npx pittaya@latest add multi-select
When to use
Use Multi-Select when users need to choose multiple values from a large list of options. It's especially useful when:
- The list has more than 5 options and needs search functionality for easier navigation
- You need to visually display selected items as badges
- Users can quickly add or remove items without reopening the menu
- You're building advanced filters, tags, categories, or user/group selection
Best practices
- Use descriptive
placeholdertext like "Select categories..." or "Choose members..." - Configure
maxCountwhen many items are selected to avoid visual clutter - Provide a helpful
emptyMessagewhen search returns no results - Keep option labels concise and easy to scan
- Combine with form validation to ensure users select enough items
- For very long lists (100+ items), consider implementing pagination or lazy loading
Form Integration
Multi-Select integrates seamlessly with popular form libraries like React Hook Form. The component accepts value and onChange props, making it compatible with any form state management solution.
With React Hook Form, you can use the Controller component to wrap Multi-Select and get full validation support, error handling, and form state management out of the box.
✨ Easy React Hook Form Integration
See the "React Hook Form" example below for a complete implementation with validation and error messages.
Accessibility
Multi-Select is built on top of accessible Radix UI components and includes:
- Full keyboard navigation support (Tab, Enter, Escape, Arrow keys)
- Appropriate ARIA attributes (
role="combobox",aria-expanded) - Visible focus states on all interactive elements
- Badge removal buttons are focusable and keyboard-operable
- Integrated search field for easier item location
Always provide descriptive labels using <label> associated with the component to enhance screen reader experience.
Examples
Combine variants and sizes to meet your needs.
Basic usage
A simple Multi-Select example with state control.
React Hook Form
Complete integration with React Hook Form including validation and error handling.
With display limit
Use maxCount to show a counter when many items are selected.
Team member selection
Practical example of selecting users to add to a project or group.
Product filters
Example of usage in e-commerce filters for categories, brands, and tags.
Skills selection
Example of a professional profile form with skills selection.
Disabled state
Multi-Select can be disabled to prevent interaction.
Properties
TSX interface that combines variants and default attributes.
| Prop | Type | Default | Description |
|---|---|---|---|
options | MultiSelectOption[] | — | Array of objects with {label: string, value: string} representing the available options for selection. |
value | string[] | [] | Array of currently selected values. Use with onChange to control state. |
onChange | (value: string[]) => void | — | Callback executed when selected values change. Receives the new array of values. |
placeholder | string | 'Select items...' | Text displayed when no items are selected. |
emptyMessage | string | 'No items found.' | Message displayed when search returns no results. |
maxCount | number | — | Maximum number of badges to display before showing a counter (e.g., '5 selected'). Useful for many selected items. |
disabled | boolean | false | Disables interaction with the component, applying appropriate visual styles. |
className | string | — | Additional CSS classes to customize the trigger button style. |