Searchable Dropdown
A dropdown menu with search/filter functionality and smooth animations.
Installation
npx smoothui-cli add searchable-dropdownFeatures
- Real-time search filtering with smooth transitions
- Support for item descriptions and icons
- Keyboard navigation (Escape to close)
- Animated clear button for search input
- Staggered animation for filtered results
- Empty state message when no results found
- Click outside to close
- Fully accessible and customizable
Accessibility
Keyboard Interactions
| Key | Description |
|---|---|
Enter / Space | Opens the dropdown when the trigger button is focused, or selects the focused item |
Escape | Closes the dropdown, clears the search, and returns focus to the trigger button |
Arrow Down | Moves focus to the next filtered item (wraps to first) |
Arrow Up | Moves focus to the previous filtered item (wraps to last) |
Home | Moves focus to the first filtered item |
End | Moves focus to the last filtered item |
ARIA Attributes
| Attribute | Element | Purpose |
|---|---|---|
aria-expanded | Trigger button | Indicates whether the dropdown is open or closed |
aria-haspopup="listbox" | Trigger button | Indicates the button opens a listbox |
aria-label | Trigger button | Provides an accessible name including the selected item label |
role="combobox" | Search input | Identifies the search field as a combobox |
aria-autocomplete="list" | Search input | Indicates the input provides list-based autocomplete |
aria-controls | Search input | References the id of the dropdown items list |
aria-expanded | Search input | Indicates the dropdown state within the combobox |
aria-label | Search input | Provides an accessible name for the search field |
role="option" | List item | Identifies each item as a selectable option |
aria-selected | List item | Indicates the currently selected or focused item |
aria-label="Clear search" | Clear button | Provides an accessible name for the search clear action |
Screen Reader
- The trigger button announces its expanded/collapsed state and the currently selected value
- Each option announces its label, optional description, and selected state
- A checkmark icon includes a
<title>element for screen readers - The clear search button is announced with its label
Reduced Motion
This component respects the prefers-reduced-motion media query via useReducedMotion from Motion. When reduced motion is preferred, dropdown open/close, search field slide-in, item stagger, and chevron rotation animations are disabled instantly.
Props
Item Props
Each item in the dropdown can have the following properties:
| Property | Type | Description |
|---|---|---|
id | string | number | Unique identifier for the item |
label | string | Display text for the item |
icon | React.ReactNode | Optional icon to display before the label |
description | string | Optional description text below the label |