downshift-js/downshift

🏎 A set of primitives to build simple, flexible, WAI-ARIA compliant React autocomplete, combobox or select dropdown components.

Summary

downshift is a React library that provides primitives for building accessible autocomplete, combobox, select dropdown, and tag group components. It ships a set of hooks (useSelect, useCombobox, useTagGroup) that follow the WAI-ARIA 1.2 combobox pattern, plus a render-prop component for older codebases. The library manages interaction state (highlighting, keyboard navigation, ARIA attributes) while leaving the actual UI markup to the developer.

What it is useful for

Engineers reach for downshift when they need a dropdown, autocomplete, or multi-select input in a React app and want screen reader support without hand-rolling ARIA. Common scenarios include search-as-you-type fields, single-select pickers, and tag-style multi-select inputs. The hooks-based API fits design systems where each team wants to render their own markup but share keyboard and accessibility behavior. The README also notes out-of-the-box Preact support, so the same primitive can be reused in Preact applications via import Downshift from 'downshift/preact'.

How engineers can use it

Install it as a project dependency with:

npm install --save downshift

React is a required peer dependency. For new code the README recommends the hooks over the render-prop component. A typical useSelect or useCombobox hook returns state plus "prop getters" (getInputProps, getItemProps, getMenuProps, getLabelProps, getRootProps) that you spread onto your own elements. The README's worked example is a fruit combobox: you keep an items array, the hook tracks isOpen, inputValue, highlightedIndex, and selectedItem, and you map over filtered items to render <li> elements with props from getItemProps.

Two props worth understanding up front:

• itemToString is needed when items are objects, and the README explicitly warns it must handle null, since pressing Escape invokes it.
• stateReducer intercepts state changes by type (e.g. keyDownEnter, clickItem) and is the documented way to keep the menu open after selection.

The original Downshift render-prop component is still exported but is treated as legacy. The README states it does not implement the latest ARIA 1.2 combobox pattern that the hooks do, and it is slated for removal once the hooks are considered mature. The README also notes that omitting getRootProps from the render-prop component reduces screen reader support, so follow the documented structure when accessibility matters. Full hook-specific documentation lives in separate READMEs linked from the main page.