<h1 align="center"> downshift 🏎 <br> <img src="https://raw.githubusercontent.com/downshift-js/downshift/master/other/public/logo/downshift.svg" alt="downshift logo" title="downshift logo" width="300"> <br> </h1> <p align="center" style="font-size: 1.2rem;">Primitives to build simple, flexible, WAI-ARIA compliant React autocomplete, combobox or select dropdown components.</p>

Read the docs | See the intro blog post | Listen to the Episode 79 of the Full Stack Radio podcast

<hr />

[![Build Status][build-badge]][build] [![Code Coverage][coverage-badge]][coverage] [![downloads][downloads-badge]][npmcharts] [![version][version-badge]][package] [![MIT License][license-badge]][license]

[![PRs Welcome][prs-badge]][prs] [![Chat][chat-badge]][chat] [![Code of Conduct][coc-badge]][coc] [![Join the community on Spectrum][spectrum-badge]][spectrum]

[![Supports React and Preact][react-badge]][react] [![size][size-badge]][unpkg-dist] [![gzip size][gzip-badge]][unpkg-dist] [![module formats: umd, cjs, and es][module-formats-badge]][unpkg-dist]

The problem

You need an autocomplete, a combobox or a select experience in your application and you want it to be accessible. You also want it to be simple and flexible to account for your use cases. Finally, it should follow the [ARIA][aria] design pattern for a [combobox][combobox-aria-example] or a [select][select-aria-example], depending on your use case.

This solution

The library offers a couple of solutions. The first solution, which is the one we recommend you to try first, is a set of React hooks. Each hook provides the stateful logic needed to make the corresponding component functional and accessible. Navigate to the documentation for each by using the links in the list below.

[useSelect][useselect-readme] for a custom select component.
[useCombobox][combobox-readme] for a combobox or autocomplete input.
[useTagGroup][tag-group-readme] for a tag group component. Also useful to build a multiple selection combobox or select component with tags.

The second solution is the Downshift component, which can also be used to create accessible combobox and select components, providing the logic in the form of a render prop. It served as inspiration for developing the hooks and it has been around for a while. It established a successful pattern for making components accessible and functional while giving developers complete freedom when building the UI.

Both useSelect and useCombobox support the latest ARIA combobox patterns for W3C, which Downshift does not. Consequently, we strongly recommend the you use the hooks. The hooks have been migrated to the ARIA 1.2 combobox pattern in the version 7 of downshift. There is a [Migration Guide][migration-guide-v7] that documents the changes introduced in version 7.

The README on this page covers only the component while each hook has its own README page. You can navigate to the [hooks page][hooks-readme] or go directly to the hook you need by using the links in the list above.

For examples on how to use the hooks or the Downshift component, check out our [docsite][docsite]!

🚨 Use the Downshift hooks 🚨

If you are new to the library, consider the useSelect and useCombobox hooks as the first option. As mentioned above, the hooks benefit from the updated ARIA patterns and are actively maintained and improved. If there are use cases that are supported by the Downshift component and not by the hooks, please create an issue in our repo. The Downshift component is going to be removed completely once the hooks become mature.

Downshift

This is a component that controls user interactions and state for you so you can create autocomplete, combobox or select dropdown components. It uses a [render prop][use-a-render-prop] which gives you maximum flexibility with a minimal API because you are responsible for the rendering of everything and you simply apply props to what you're rendering.

This differs from other solutions which render things for their use case and then expose many options to allow for extensibility resulting in a bigger API that is less flexible as well as making the implementation more complicated and harder to contribute to.

NOTE: The original use case of this component is autocomplete, however the API is powerful and flexible enough to build things like dropdowns as well.

Installation
Usage
Basic Props
Advanced Props
stateChangeTypes
Control Props
Children Function
- prop getters
- actions
- state
- props
Event Handlers
- default handlers
- customizing handlers
Utilities
- resetIdCounter
React Native
- Gotchas
Advanced React Component Patterns course
Examples
FAQ
Inspiration
Other Solutions
Bindings for ReasonML
Contributors
LICENSE

Installation

This module is distributed via [npm][npm] which is bundled with [node][node] and should be installed as one of your project's dependencies:

npm install --save downshift

This package also depends on react. Please make sure you have it installed as well.

Note also this library supports preact out of the box. If you are using preact then use the corresponding module in the preact/dist folder. You can even import Downshift from 'downshift/preact' 👍

Usage

[Try it out in the browser][code-sandbox-try-it-out]

import * as React from 'react'
import {render} from 'react-dom'
import Downshift from 'downshift'

const items = [
  {value: 'apple'},
  {value: 'pear'},
  {value: 'orange'},
  {value: 'grape'},
  {value: 'banana'},
]

render(
  <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>
        <div
          style={{display: 'inline-block'}}
          {...getRootProps({}, {suppressRefError: true})}
        >
          <input {...getInputProps()} />
        </div>
        <ul {...getMenuProps()}>
          {isOpen
            ? items
                .filter(item => !inputValue || item.value.includes(inputValue))
                .map((item, index) => (
                  <li
                    {...getItemProps({
                      key: item.value,
                      index,
                      item,
                      style: {
                        backgroundColor:
                          highlightedIndex === index ? 'lightgray' : 'white',
                        fontWeight: selectedItem === item ? 'bold' : 'normal',
                      },
                    })}
                  >
                    {item.value}
                  </li>
                ))
            : null}
        </ul>
      </div>
    )}
  </Downshift>,
  document.getElementById('root'),
)

There is also an [example without getRootProps][code-sandbox-no-get-root-props].

Warning: The example without getRootProps is not fully accessible with screen readers as it's not possible to achieve the HTML structure suggested by ARIA. We recommend following the example with getRootProps. Examples on how to use Downshift component with and without getRootProps are on the docsite.

Downshift is the only component exposed by this package. It doesn't render anything itself, it just calls the render function and renders that. ["Use a render prop!"][use-a-render-prop]! <Downshift>{downshift => <div>/* your JSX here! */</div>}</Downshift>.

Basic Props

This is the list of props that you should probably know about. There are some advanced props below as well.

children

function({}) | required

This is called with an object. Read more about the properties of this object in the section "[Chi

Downshift

Install / Use

README

The problem

This solution

Downshift

Table of Contents

Installation

Usage

Basic Props

children