Overview
GroupedMultiSelect provides a two-tier selection interface where items are organized into collapsible groups. Group headers are non-selectable and act as category labels, while individual items can be selected with checkboxes. Ideal for filtering by hierarchical categories like trait types and traits.
Key Features
- Collapsible group headers (non-selectable categories)
- Checkbox selection with visual checkmarks
- Icons for both groups and items
- Smart trigger display: single item name or "N selected"
- Search filtering across all items
- Badge showing selected count per group
Interactive Examples
Live Demo
Selected: None
Pre-selected Items
Selected: windows-11, iphone
Disabled State
Interfaces
GroupedMultiSelectGroup
| 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 |
items | GroupedMultiSelectItem[] | Array of selectable items within this group |
GroupedMultiSelectItem
| Prop | Type | Description |
|---|---|---|
id | string | Unique identifier for the item |
label | string | Display label for the item |
icon | IconDefinition? | Optional icon for the item |
groupId | string | Parent group ID this item belongs to |
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
groups | GroupedMultiSelectGroup[] | required | Array of groups containing selectable items |
selected | string[] | required | Array of currently selected item IDs |
onChange | (selected: string[]) => void | required | Callback when selection changes |
placeholder | string | 'Select items...' | Text shown when nothing is selected |
disabled | boolean | false | Disable all interactions |
className | string | - | Additional CSS classes for the trigger button |
Usage
import { GroupedMultiSelect, type GroupedMultiSelectGroup } from '@/ui/components';
import { faDesktop, faMobile, faDisplay, faLaptop } from '@fortawesome/sharp-duotone-light-svg-icons';
// Define groups with their items
const groups: GroupedMultiSelectGroup[] = [
{
id: 'os',
label: 'Operating System',
icon: faDesktop,
items: [
{ id: 'windows-11', label: 'Windows 11', icon: faDisplay, groupId: 'os' },
{ id: 'macos', label: 'macOS Sonoma', icon: faLaptop, groupId: 'os' },
],
},
{
id: 'device',
label: 'Device Type',
icon: faMobile,
items: [
{ id: 'iphone', label: 'iPhone', groupId: 'device' },
{ id: 'android', label: 'Android', groupId: 'device' },
],
},
];
// Usage in component
const [selected, setSelected] = useState<string[]>([]);
<GroupedMultiSelect
groups={groups}
selected={selected}
onChange={setSelected}
placeholder="Filter by traits..."
/>