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

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 = (option: Option) => {
    console.log(option.value)
  }

  return (
    <Dropdown
      aria-label="Number"
      options={options}
      onChange={handleChange}
      placeholder="Select an option"
    />
  )
}

Primitive options are supported too:

<Dropdown options={['one', 'two', 'three']} defaultValue="one" />

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}
/>

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} />

Or use aria-label when there is no visible label:

<Dropdown aria-label="Country" options={countries} />

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.

Forms

Pass name to include the selected value in native form submission:

<Dropdown name="country" options={countries} defaultValue="au" />

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)}
/>

Options may also define className and data:

const options = [
  {
    value: 'one',
    label: 'One',
    className: 'important-option',
    data: { analytics: 'option-one' },
  },
]

API

Prop	Type	Default	Purpose
options	DropdownEntry[]	required	Primitive options, option objects, or groups.
value	Option | string | number | boolean | null	—	Controlled selected value.
defaultValue	same as value	null	Initial uncontrolled value.
open	boolean	—	Controlled popup state.
defaultOpen	boolean	false	Initial uncontrolled popup state.
onChange	(option: Option) => void	—	Called after a user selects an option.
onOpenChange	(open: boolean) => void	—	Called when the popup requests an open-state change.
onFocus	(open: boolean) => void	—	Called when the trigger receives focus.
placeholder	ReactNode	"Select..."	Content shown without a selection.
disabled	boolean	false	Disables the trigger.
name	string	—	Adds a hidden form input.
form	string	—	Associates the hidden input with a form ID.
id	string	generated	Sets the trigger ID and derived popup IDs.
tabIndex	number	browser default	Overrides the trigger's tab order.
aria-label	string	—	Gives the control an accessible name.
aria-labelledby	string	—	References a visible label.
renderOption	(option, state) => ReactNode	option label	Custom option contents.
noOptionsContent	ReactNode	"No options found"	Empty-state contents.
arrowClosed / arrowOpen	ReactNode	CSS arrow	Custom trigger arrows. Provide both.

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

License

MIT