React Autocomplete and Select Component Libraries
downshift, react-autocomplete, and react-select are React libraries for building autocomplete inputs, dropdowns, and selection interfaces. downshift is a headless utility that provides state management and accessibility primitives while leaving all rendering to the developer. react-autocomplete is a minimal, unstyled component using render props for basic autocomplete functionality. react-select is a fully-featured, styled select component with built-in support for async options, multi-selection, and theming. All three aim to simplify creating accessible selection UIs, but they differ significantly in philosophy, feature set, and maintenance status.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Building Autocomplete UIs in React: downshift vs react-autocomplete vs react-select
When you need to add a search-as-you-type input or a dropdown selector to your React app, three packages often come up: downshift, react-autocomplete, and react-select. They all solve similar problems but with very different philosophies. Let’s break down how they work, where they shine, and what trade-offs you’ll face.
🧩 Core Philosophy: Control vs Convention
downshift gives you complete control over rendering and behavior. It’s a headless utility that manages the complex state logic (like keyboard navigation, focus, and ARIA attributes) but leaves every visual detail up to you.
// downshift: fully custom render
import { useCombobox } from 'downshift';
function CustomAutocomplete({ items }) {
const {
isOpen,
getInputProps,
getToggleButtonProps,
getMenuProps,
getItemProps,
highlightedIndex
} = useCombobox({ items });
return (
<div>
<input {...getInputProps()} />
<button {...getToggleButtonProps()}>▼</button>
<ul {...getMenuProps()}>
{isOpen && items.map((item, index) => (
<li
key={item.id}
{...getItemProps({ item, index })}
style={{ backgroundColor: highlightedIndex === index ? '#eee' : 'white' }}
>
{item.name}
</li>
))}
</ul>
</div>
);
}
react-autocomplete is a minimalist, unstyled component that handles basic autocomplete behavior but expects you to provide most of the rendering logic. It’s less opinionated than react-select but more prescriptive than downshift.
// react-autocomplete: render props pattern
import Autocomplete from 'react-autocomplete';
function BasicAutocomplete({ items }) {
return (
<Autocomplete
items={items}
getItemValue={(item) => item.name}
renderItem={(item, isHighlighted) => (
<div style={{ background: isHighlighted ? '#eee' : 'white' }}>
{item.name}
</div>
)}
inputProps={{ placeholder: 'Search...' }}
/>
);
}
react-select is a fully-featured, styled component out of the box. It includes theming, async loading, multi-select, and many other features with minimal setup. You can customize it, but you’re working within its design system.
// react-select: batteries-included
import Select from 'react-select';
function StyledSelect({ options }) {
return (
<Select
options={options}
placeholder="Choose an option..."
isSearchable
/>
);
}
⚙️ Accessibility and Keyboard Navigation
All three packages aim for accessibility, but their approaches differ:
-
downshiftstrictly follows WAI-ARIA practices and gives you full control over ARIA attributes. You must implement proper roles and labels yourself, but the underlying state management ensures correct keyboard handling (arrow keys, Enter, Escape). -
react-autocompleteprovides basic keyboard navigation (arrow keys, Enter) but leaves ARIA implementation to you. Its documentation includes accessibility notes, but it’s not as comprehensive asdownshift. -
react-selectships with built-in ARIA compliance and extensive keyboard support (including type-to-search, tab navigation, and screen reader announcements). It’s the most accessible out of the box.
🎨 Styling and Customization
downshift has zero built-in styles. You bring your own CSS, CSS-in-JS, or styling library. This makes it ideal for design systems that require pixel-perfect control.
react-autocomplete also has no default styles, but its API is less flexible for complex layouts (e.g., it doesn’t easily support custom dropdown headers or footers).
react-select uses emotion for styling and supports theming via a styles prop or a theme function. You can override any part of its appearance, but escaping its component structure can be challenging if you need radically different markup.
// react-select: custom styling
const customStyles = {
control: (provided) => ({
...provided,
border: '2px solid blue',
borderRadius: '8px'
}),
option: (provided, state) => ({
...provided,
backgroundColor: state.isFocused ? '#f0f0f0' : 'white'
})
};
<Select styles={customStyles} options={options} />
📦 Advanced Features
Async Loading:
downshift: You manage data fetching yourself; just update theitemsprop.react-autocomplete: Pass anonMenuOpenor handle input changes to fetch data.react-select: Built-inloadOptionsprop for async options with loading indicators.
Multi-select:
downshift: Possible but requires manual state management for selected items.react-autocomplete: Not supported out of the box.react-select: Enable withisMultiprop.
Creatable Options (allowing users to add new items):
downshift: Implement yourself by checking input value against items.react-autocomplete: Not built-in.react-select: Use theCreatableSelectcomponent fromreact-select/creatable.
⚠️ Maintenance Status
As of 2024:
-
react-autocompleteis deprecated. Its npm page states: "This package is no longer maintained. Please usedownshiftinstead." New projects should avoid it. -
downshiftandreact-selectare actively maintained with regular updates and strong community support.
🛠️ Real-World Decision Guide
When to use downshift
- You need full control over markup and behavior
- You’re building a design system or custom component library
- You require complex interactions (e.g., combobox + tag input)
- Your team values explicit, testable state logic
When to use react-autocomplete
- Do not use in new projects — it’s deprecated and lacks modern features
- Only consider for maintaining legacy codebases that already depend on it
When to use react-select
- You need a production-ready select with minimal effort
- Your design aligns with its default look or can be themed easily
- You require advanced features like async loading, multi-select, or creatable options
- You want built-in accessibility without deep ARIA knowledge
📊 Summary Table
| Feature | downshift | react-autocomplete | react-select |
|---|---|---|---|
| Maintenance | ✅ Active | ❌ Deprecated | ✅ Active |
| Styling | 💯 Zero styles (headless) | 💯 Zero styles | 🎨 Themed (emotion) |
| Accessibility | ✅ Manual ARIA | ⚠️ Basic | ✅ Built-in |
| Multi-select | ⚙️ Manual impl | ❌ No | ✅ isMulti prop |
| Async Support | ⚙️ Manual fetch | ⚙️ Manual fetch | ✅ loadOptions |
| Learning Curve | Steeper | Moderate | Gentle |
💡 Final Recommendation
- Start with
react-selectif you need a quick, robust solution that works out of the box. - Reach for
downshiftwhen you hit the limits ofreact-selector need to build something truly custom. - Avoid
react-autocompletefor new work — its functionality is better served by the other two, and it’s no longer maintained.
The right choice depends on your project’s needs: speed and convention (react-select) versus flexibility and control (downshift).
How to Choose: react-autocomplete vs downshift vs react-select
- react-autocomplete:
Do not choose
react-autocompletefor new projects — it is officially deprecated according to its npm page, which recommends usingdownshiftinstead. Only consider it if you're maintaining an existing codebase that already depends on it, and plan to migrate to a maintained alternative soon. - downshift:
Choose
downshiftwhen you need complete control over the UI and behavior of your autocomplete or select component. It's ideal for design systems, custom component libraries, or complex interactions that don't fit standard patterns. Be prepared to handle all rendering, styling, and some accessibility details yourself, though it provides excellent state management and keyboard navigation logic. - react-select:
Choose
react-selectwhen you need a production-ready, accessible select component with minimal setup. It's perfect for standard use cases like dropdowns, multi-select, async loading, and creatable options. Its built-in theming and comprehensive feature set make it a great choice when your design requirements align with its capabilities or can be reasonably customized.
Popular Comparisons
README for react-autocomplete
React Autocomplete 
Accessible, extensible, Autocomplete for React.js.
<Autocomplete
getItemValue={(item) => item.label}
items={[
{ label: 'apple' },
{ label: 'banana' },
{ label: 'pear' }
]}
renderItem={(item, isHighlighted) =>
<div style={{ background: isHighlighted ? 'lightgray' : 'white' }}>
{item.label}
</div>
}
value={value}
onChange={(e) => value = e.target.value}
onSelect={(val) => value = val}
/>
Check out more examples and get stuck right in with the online editor.
Install
npm
npm install --save react-autocomplete
yarn
yarn add react-autocomplete
AMD/UMD
- Development: https://unpkg.com/react-autocomplete@1.8.0/dist/react-autocomplete.js
- Production: https://unpkg.com/react-autocomplete@1.8.0/dist/react-autocomplete.min.js
API
Props
getItemValue: Function
Arguments: item: Any
Used to read the display value from each entry in items.
items: Array
The items to display in the dropdown menu
renderItem: Function
Arguments: item: Any, isHighlighted: Boolean, styles: Object
Invoked for each entry in items that also passes shouldItemRender to
generate the render tree for each item in the dropdown menu. styles is
an optional set of styles that can be applied to improve the look/feel
of the items in the dropdown menu.
autoHighlight: Boolean (optional)
Default value: true
Whether or not to automatically highlight the top match in the dropdown menu.
inputProps: Object (optional)
Default value: {}
Props passed to props.renderInput. By default these props will be
applied to the <input /> element rendered by Autocomplete, unless you
have specified a custom value for props.renderInput. Any properties
supported by HTMLInputElement can be specified, apart from the
following which are set by Autocomplete: value, autoComplete, role,
aria-autocomplete. inputProps is commonly used for (but not limited to)
placeholder, event handlers (onFocus, onBlur, etc.), autoFocus, etc..
isItemSelectable: Function (optional)
Default value: function() { return true }
Arguments: item: Any
Invoked when attempting to select an item. The return value is used to determine whether the item should be selectable or not. By default all items are selectable.
menuStyle: Object (optional)
Default value:
{
borderRadius: '3px',
boxShadow: '0 2px 12px rgba(0, 0, 0, 0.1)',
background: 'rgba(255, 255, 255, 0.9)',
padding: '2px 0',
fontSize: '90%',
position: 'fixed',
overflow: 'auto',
maxHeight: '50%', // TODO: don't cheat, let it flow to the bottom
}
Styles that are applied to the dropdown menu in the default renderMenu
implementation. If you override renderMenu and you want to use
menuStyle you must manually apply them (this.props.menuStyle).
onChange: Function (optional)
Default value: function() {}
Arguments: event: Event, value: String
Invoked every time the user changes the input's value.
onMenuVisibilityChange: Function (optional)
Default value: function() {}
Arguments: isOpen: Boolean
Invoked every time the dropdown menu's visibility changes (i.e. every time it is displayed/hidden).
onSelect: Function (optional)
Default value: function() {}
Arguments: value: String, item: Any
Invoked when the user selects an item from the dropdown menu.
open: Boolean (optional)
Used to override the internal logic which displays/hides the dropdown
menu. This is useful if you want to force a certain state based on your
UX/business logic. Use it together with onMenuVisibilityChange for
fine-grained control over the dropdown menu dynamics.
renderInput: Function (optional)
Default value:
function(props) {
return <input {...props} />
}
Arguments: props: Object
Invoked to generate the input element. The props argument is the result
of merging props.inputProps with a selection of props that are required
both for functionality and accessibility. At the very least you need to
apply props.ref and all props.on<event> event handlers. Failing to do
this will cause Autocomplete to behave unexpectedly.
renderMenu: Function (optional)
Default value:
function(items, value, style) {
return <div style={{ ...style, ...this.menuStyle }} children={items}/>
}
Arguments: items: Array<Any>, value: String, styles: Object
Invoked to generate the render tree for the dropdown menu. Ensure the
returned tree includes every entry in items or else the highlight order
and keyboard navigation logic will break. styles will contain
{ top, left, minWidth } which are the coordinates of the top-left corner
and the width of the dropdown menu.
selectOnBlur: Boolean (optional)
Default value: false
Whether or not to automatically select the highlighted item when the
<input> loses focus.
shouldItemRender: Function (optional)
Arguments: item: Any, value: String
Invoked for each entry in items and its return value is used to
determine whether or not it should be displayed in the dropdown menu.
By default all items are always rendered.
sortItems: Function (optional)
Arguments: itemA: Any, itemB: Any, value: String
The function which is used to sort items before display.
value: Any (optional)
Default value: ''
The value to display in the input field
wrapperProps: Object (optional)
Default value: {}
Props that are applied to the element which wraps the <input /> and
dropdown menu elements rendered by Autocomplete.
wrapperStyle: Object (optional)
Default value:
{
display: 'inline-block'
}
This is a shorthand for wrapperProps={{ style: <your styles> }}.
Note that wrapperStyle is applied before wrapperProps, so the latter
will win if it contains a style entry.
Imperative API
In addition to the props there is an API available on the mounted element which is similar to that of HTMLInputElement. In other words: you can access most of the common <input> methods directly on an Autocomplete instance. An example:
class MyComponent extends Component {
componentDidMount() {
// Focus the input and select "world"
this.input.focus()
this.input.setSelectionRange(6, 11)
}
render() {
return (
<Autocomplete
ref={el => this.input = el}
value="hello world"
...
/>
)
}
}
Development
You can start a local development environment with npm start. This command starts a static file server on localhost:8080 which serves the examples in examples/. Hot-reload mechanisms are in place which means you don't have to refresh the page or restart the build for changes to take effect.
Tests!
Run them:
npm test
Write them:
lib/__tests__/Autocomplete-test.js
Check your work:
npm run coverage
Scripts
Run with npm run <script>.
gh-pages
Builds the examples and assembles a commit which is pushed to origin/gh-pages, then cleans up your working directory. Note: This script will git checkout master before building.
release
Takes the same argument as npm publish, i.e. [major|minor|patch|x.x.x], then tags a new version, publishes, and pushes the version commit and tag to origin/master. Usage: npm run release -- [major|minor|patch|x.x.x]. Remember to update the CHANGELOG before releasing!
build
Runs the build scripts detailed below.
build:component
Transpiles the source in lib/ and outputs it to build/, as well as creating a UMD bundle in dist/.
build:examples
Creates bundles for each of the examples, which is used for pushing to origin/gh-pages.
test
Runs the test scripts detailed below.
test:lint
Runs eslint on the source.
test:jest
Runs the unit tests with jest.
coverage
Runs the unit tests and creates a code coverage report.
start
Builds all the examples and starts a static file server on localhost:8080. Any changes made to lib/Autocomplete.js and the examples are automatically compiled and transmitted to the browser, i.e. there's no need to refresh the page or restart the build during development. This script is the perfect companion when making changes to this repo, since you can use the examples as a test-bed for development.