react-dropdown
A lightweight, accessible dropdown component for React 18 and 19.
react-dropdown is for the common case where a native <select> is too difficult to style, but a large select framework would be excessive. It supports single selection, option groups, controlled and uncontrolled state, custom rendering, keyboard navigation, and TypeScript without runtime dependencies.
Install
npm install react-dropdown copy
Import the component and its default styles:
import Dropdown, { type Option } from 'react-dropdown'
import 'react-dropdown/style.css'
const options = [
{ value: 'one' , label: 'One' },
{ value: 'two' , label: 'Two' },
{
type: 'group' as const ,
name: 'More' ,
items: [
{ value: 'three' , label: 'Three' },
{ value: 'four' , label: 'Four' , disabled: true },
],
},
]
function Example () {
const handleChange
Primitive options are supported too:
< Dropdown options={ [ 'one' , 'two' , 'three' ] } defaultValue= "one" /> copy
String, number, and boolean values are supported. Labels may be any ReactNode.
Controlled state
Control the selected value, the open state, or both:
const [value, setValue] = useState < Option | null >(null)
const [open, setOpen] = useState ( false )
< Dropdown
options={ options }
value={ value }
onChange={ setValue }
open={ open }
onOpenChange={ setOpen }
/> copy
Use null to clear a controlled value. Use defaultValue or defaultOpen for uncontrolled initial state.
Accessible labels
Give every dropdown an accessible name with a visible label:
< label id= "country-label" > Country </ label >
< Dropdown aria-labelledby= "country-label" options={ countries } /> copy
Or use aria-label when there is no visible label:
< Dropdown aria-label= "Country" options={ countries } /> copy
The trigger implements a select-only combobox with a listbox popup. It supports:
Enter or Space to open and select.
ArrowDown and ArrowUp to open and move through options.
Home and End to move to the first or last enabled option.
Escape to close.
Tab to close and continue normal page navigation.
Disabled options, named groups, selected state, and active-descendant announcements.
Pass name to include the selected value in native form submission:
< Dropdown name= "country" options={ countries } defaultValue= "au" /> copy
The component renders a hidden input using the selected option value. Pass form to associate it with a form by ID.
Custom rendering
< Dropdown
options={ options }
renderOption={ (option, { active, selected }) => (
< span >
{ selected ? '✓ ' : '' }
{ option.label }
{ active ? ' ←' : '' }
</ span >
) }
optionClassName={ (_option, state) => (state.active ? 'my-active-option' : undefined) }
/> copy
Options may also define className and data:
const options = [
{
value: 'one' ,
label: 'One' ,
className: 'important-option' ,
data: { analytics: 'option-one' },
},
] copy
API
Prop Type Default Purpose optionsDropdownEntry[]required Primitive options, option objects, or groups. valueOption | string | number | boolean | null— Controlled selected value. defaultValuesame as value nullInitial uncontrolled value. openboolean— Controlled popup state. defaultOpenbooleanfalseInitial uncontrolled popup state.
The styling props are baseClassName, className, controlClassName, placeholderClassName, menuClassName, optionClassName, and arrowClassName.
The forwarded ref points to the trigger HTMLButtonElement.
Styling
The default stylesheet retains the familiar class names:
.Dropdown-root
.Dropdown-control
.Dropdown-placeholder
.Dropdown-arrow-wrapper and .Dropdown-arrow
.Dropdown-menu
.Dropdown-group and .Dropdown-title
.Dropdown-option
.Dropdown-noresults
State classes include .is-open, .is-selected, .is-active, and .is-disabled.
Set baseClassName to replace the Dropdown prefix when supplying all of your own styles.
Migrating from 1.x
Version 2 is a deliberate accessibility and packaging reset:
React 18 or 19 is required.
The package now ships ESM and CommonJS with an exports map.
The trigger is a focusable button with role="combobox"; CSS that assumes .Dropdown-control is a <div> may need adjustment.
onFocus now runs when the trigger actually receives focus.
onChange returns the complete normalized option, including className, disabled, and data when present.
value={null} clears a controlled selection. 0 and false are valid values.
The menu uses semantic <ul> and <li> elements. Prefer class selectors over element selectors in custom CSS.
optionClassName, renderOption, open, and onOpenChange replace common 1.x workarounds.
The old global .Dropdown-disabled class is now applied directly to the disabled control.
Development
npm install
npm run dev # local example
npm test # interaction tests
npm run typecheck
npm run build
npm run check # all release checks copy
License
MIT