Guide · Open source
How to use Downshift: build an accessible React autocomplete
Updated · written with AI from the project's own documentation and checked against our catalogue data
Downshift is a JavaScript library for React that handles the behavior and state of dropdown-style inputs such as autocomplete boxes, comboboxes and select menus. You write the markup and styling, and it supplies keyboard handling, highlighting and WAI-ARIA attributes. This guide shows how to install it, which API to pick, and how the basic pieces fit together.
downshiftdownshift-js/downshift · ★ 12.3k · MIT Install options & downloads Quick start
- 1Install the package. Run npm install --save downshift in your React project. Make sure react is also installed.
- 2Pick a hook. Use useCombobox for autocomplete, useSelect for a custom select, or useTagGroup for tags, as the README recommends.
- 3Render your own markup. Downshift gives you no styled UI, so write the input, list and items yourself.
- 4Connect the props. Apply the returned props and handlers to your elements so keyboard and ARIA behaviour work.
- 5Style the highlighted item. Use the highlighted state to change how the active item looks.
- 6Read the docs for details. Check the docsite and each hook's README for the full API.
Check the prerequisites
Downshift is built for React or Preact, so your project needs one of those. The library is distributed via npm and should be installed as one of your project's dependencies. It also depends on react, so make sure react is installed as well.
If you use Preact, the README says the library supports it out of the box and you can import Downshift from 'downshift/preact'.
- Node.js and npm
- React or Preact
Install Downshift with npm
Run the install command from your project folder. The README uses the --save flag so the package is recorded as a dependency.
npm install --save downshiftChoose a hook or the Downshift component
The README recommends a set of hooks over the older Downshift component. useSelect is for a custom select, useCombobox is for a combobox or autocomplete input, and useTagGroup is for a tag group, which can also help build a multiple selection input with tags.
The Downshift component uses a render prop and still works, but the README says the hooks use the updated ARIA 1.2 combobox pattern, and that the component is going to be removed once the hooks are mature. For new work, start with the hooks. The README also points to a migration guide for version 7 changes.
- useSelect: custom select component
- useCombobox: combobox or autocomplete input
- useTagGroup: tag group, or multiple selection with tags
Understand the render prop example
The README's usage example uses the Downshift component. You pass an itemToString function so Downshift can turn an item into text, and an onChange handler that runs when a selection is made. The children function receives prop getters such as getInputProps, getItemProps, getLabelProps and getMenuProps, plus state such as isOpen, inputValue and highlightedIndex.
You apply the prop getters to your own elements. Downshift handles the events and attributes, while you decide the markup and styling. The example highlights the active item with a background colour based on highlightedIndex.
- Spread getInputProps() onto an input element
- Spread getMenuProps() onto a ul and getItemProps() onto each li, passing index and item
- Use isOpen to decide whether to render the list
<Downshift
onChange={selection =>
alert(selection ? `You selected ${selection.value}` : 'Selection Cleared')
}
itemToString={item => (item ? item.value : '')}
>
{({ getInputProps, getItemProps, getLabelProps, getMenuProps, isOpen, inputValue, highlightedIndex, selectedItem, getRootProps }) => (
<div>
<label {...getLabelProps()}>Enter a fruit</label>
<input {...getInputProps()} />
<ul {...getMenuProps()}>
{isOpen ? items.filter(item => !inputValue || item.value.includes(inputValue)).map((item, index) => (
<li {...getItemProps({ key: item.value, index, item })}>{item.value}</li>
)) : null}
</ul>
</div>
)}
</Downshift>Learn the main props and handlers
The README's table of contents lists the component's props, grouped as basic and advanced. Basic props include children, itemToString, onChange and stateReducer. Advanced props include initialSelectedItem, initialInputValue, onSelect, onStateChange, onInputValueChange, itemCount and getA11yStatusMessage.
Control props such as isOpen, inputValue, highlightedIndex and selectedItem let you take over state yourself. The README also covers actions, state, props and event handlers for customising behaviour. Check the docsite and the hook READMEs for the full details of each.
- itemToString converts items to text
- onChange and onSelect report selections
- Control props let you own the state
Where to find more examples
The README links to a docsite with examples for the hooks and the component, and to a CodeSandbox option to try the usage example in the browser. Each hook also has its own README page, which is the best place to look for the exact API of useSelect, useCombobox or useTagGroup.
What people use it for
- Search-as-you-type autocomplete for a list of products or cities
- A custom select menu styled to match your design system
- A multi-select input that shows selected values as tags using useTagGroup
- A dropdown where you control the look and the keyboard behaviour
Frequently asked questions
How do I install downshift?
Install it with npm using npm install --save downshift. The README says it should be a project dependency, and react must also be installed.
Does downshift require React?
Downshift is built for React and Preact. The README says it supports Preact out of the box, using the preact module in the dist folder or downshift/preact import.
Is downshift free to use?
The repository is licensed under the MIT License, as shown in the README. Check the LICENSE file in the repository for the full terms.
Should I use the Downshift component or the hooks?
The README strongly recommends the hooks, useSelect and useCombobox, because they follow the newer ARIA 1.2 combobox pattern. The Downshift component is going to be removed once the hooks mature.
Does downshift come with styles?
No. The README says you render everything yourself, so you supply the markup and styling and Downshift supplies the behaviour and state.
What are alternatives to downshift?
The project lists react-select, Headless UI and Reach UI Combobox as comparable projects. Choose based on whether you want full control over markup or a more ready-made component.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Downshift suits React developers who want a custom autocomplete, combobox or select with accessibility handled for them and full control over the look. Use the hooks rather than the older component for new work. If you want a ready-made styled component out of the box, or you do not use React or Preact, pick a different tool such as react-select or Headless UI.
Install options & downloads