Overview
DittoMultiSelect is a unified multi-select component that replaces GroupedMultiSelect. It supports optional grouping (flat list by default), optional search, checkbox selection, icons on options and groups, and smart trigger display showing selected count or single label.
Key Features
- Optional grouping - flat list when groups omitted
- Checkbox selection with visual checkmarks
- Optional search filtering (opt-in via searchable prop)
- Smart trigger: single label or "N selected"
- Badge showing selected count per group
- Clearable selection with clear all button
- Size variants (default, sm)
When to Use
Use DittoMultiSelect when users need to select multiple options from a list. Add groups to organize options into categories. Enable search for lists with many options. Common use cases include filtering by multiple criteria, selecting tags, or trait assignment.
Skip When
- Single selection needed -> Use DittoSingleSelect
- Visual card selection -> Use CardPicker
- Inline tag management -> Use TagSelect
Interactive Examples
Live Demo
Selected: None
Pre-selected Items
Selected: windows-11, iphone
Flat List (No Groups)
Selected: red, blue
With Search
Selected: None
Disabled State
Size Variants
Default
Small
Interfaces
DittoSelectOption
| Prop | Type | Description |
|---|---|---|
value | string | Unique identifier for the option |
label | string | Display label |
icon | IconDefinition? | Optional Font Awesome icon |
groupId | string? | Parent group ID (only when using groups) |
disabled | boolean? | Disable this option |
DittoSelectGroup
| Prop | Type | Description |
|---|---|---|
id | string | Unique identifier for the group |
label | string | Display label for the group header |
icon | IconDefinition? | Optional icon for the group header |
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
options | DittoSelectOption[] | required | Array of selectable options |
groups | DittoSelectGroup[] | - | Optional groups for categorizing options |
value | string[] | required | Array of currently selected option values |
onChange | (value: string[]) => void | required | Callback when selection changes |
placeholder | string | Select... | Text shown when nothing is selected |
searchable | boolean | false | Enable search filtering |
searchPlaceholder | string | Search... | Placeholder for search input |
clearable | boolean | false | Show clear all button when items selected |
maxItems | number | - | Maximum number of items that can be selected |
size | 'sm' | 'default' | 'default' | Size variant |
disabled | boolean | false | Disable all interactions |
className | string | - | Additional CSS classes for the trigger button |
Usage
import {
DittoMultiSelect,
type DittoSelectOption,
type DittoSelectGroup
} from '@/ui/components';
import { faDesktop, faMobile, faDisplay, faLaptop } from '@fortawesome/duotone-regular-svg-icons';
// Define options (flat array)
const options: DittoSelectOption[] = [
{ value: 'windows-11', label: 'Windows 11', icon: faDisplay, groupId: 'os' },
{ value: 'macos', label: 'macOS Sonoma', icon: faLaptop, groupId: 'os' },
{ value: 'iphone', label: 'iPhone', groupId: 'device' },
{ value: 'android', label: 'Android', groupId: 'device' },
];
// Define groups (optional - omit for flat list)
const groups: DittoSelectGroup[] = [
{ id: 'os', label: 'Operating System', icon: faDesktop },
{ id: 'device', label: 'Device Type', icon: faMobile },
];
// Usage
const [selected, setSelected] = useState<string[]>([]);
<DittoMultiSelect
options={options}
groups={groups} // Optional - flat list if omitted
value={selected}
onChange={setSelected}
placeholder="Filter by traits..."
searchable // Optional - opt-in search
clearable // Optional - clear all button
/>