- refKey: if you're rendering a composite component, that component will need
to accept a prop which it forwards to the root DOM element. Commonly, folks
call this innerRef. So you'd call: getMenuProps({refKey: 'innerRef'}) and
your composite component would forward like:

.
However, if you are just rendering a primitive component like
, there
is no need to specify this property. It defaults to ref.

Please keep in mind that menus, for accessibility purposes, should always be
rendered, regardless of whether you hide it or not. Otherwise, getMenuProps
may throw error if you unmount and remount the menu.

- aria-label: By default the menu will add an aria-labelledby that refers to
the rendered with getLabelProps. However, if you provide
aria-label to give a more specific label that describes the options
available, then aria-labelledby will not be provided and screen readers can
use your aria-label instead.

In some cases, you might want to completely bypass the refKey check. Then you
can provide the object {suppressRefError : true} as the second argument to
getMenuProps. **Please use it with extreme care and only if you are absolutely
sure that the ref is correctly forwarded otherwise Downshift will unexpectedly
fail.**

`jsx



{!isOpen
? null
: items.map((item, index) => (

• {item.name}

))}



`

> Note that for accessibility reasons it's best if you always render this
> element whether or not downshift is in an isOpen state.

#### getItemProps

The props returned from calling this function should be applied to any menu
items you render.

This is an impure function, so it should only be called when you will
actually be applying the props to an item.

What do you mean by impure function?

Basically just don't do this:

`jsx
items.map(item => {
const props = getItemProps({item}) // we're calling it here
if (!shouldRenderItem(item)) {
return null // but we're not using props, and downshift thinks we are...
}
return


})
`

Instead, you could do this:

`jsx
items.filter(shouldRenderItem).map(item =>

)
`

Required properties:

- item: this is the item data that will be selected when the user selects a
particular item.

Optional properties:

- index: This is how downshift keeps track of your item when updating the
highlightedIndex as the user keys around. By default, downshift will
assume the index is the order in which you're calling getItemProps. This
is often good enough, but if you find odd behavior, try setting this
explicitly. It's probably best to be explicit about index when using a
windowing library like react-virtualized.
- disabled: If this is set to true, then all of the downshift item event
handlers will be omitted. Items will not be highlighted when hovered, and
items will not be selected when clicked.

#### getToggleButtonProps

Call this and apply the returned props to a button. It allows you to toggle
the Menu component. You can definitely build something like this yourself (all
of the available APIs are exposed to you), but this is nice because it will also
apply all of the proper ARIA attributes.

Optional properties:

- disabled: If this is set to true, then all of the downshift button event
handlers will be omitted (it wont toggle the menu when clicked).
- aria-label: The aria-label prop is in English. You should probably
override this yourself so you can provide translations:

`jsx
const myButton = (
{...getToggleButtonProps({
'aria-label': translateWithId(isOpen ? 'close.menu' : 'open.menu'),
})}
/>
)
`

$3

These are functions you can call to change the state of the downshift component.

| property | type | description |
| ----------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clearSelection | function(cb: Function) | clears the selection |
| clearItems | function() | Clears downshift's record of all the items. Only really useful if you render your items asynchronously within downshift. See #186 |
| closeMenu | function(cb: Function) | closes the menu |
| openMenu | function(cb: Function) | opens the menu |
| selectHighlightedItem | function(otherStateToSet: object, cb: Function) | selects the item that is currently highlighted |
| selectItem | function(item: any, otherStateToSet: object, cb: Function) | selects the given item |
| selectItemAtIndex | function(index: number, otherStateToSet: object, cb: Function) | selects the item at the given index |
| setHighlightedIndex | function(index: number, otherStateToSet: object, cb: Function) | call to set a new highlighted index |
| toggleMenu | function(otherStateToSet: object, cb: Function) | toggle the menu open state |
| reset | function(otherStateToSet: object, cb: Function) | this resets downshift's state to a reasonable default |
| setItemCount | function(count: number) | this sets the itemCount. Handy in situations where you're using windowing and the items are loaded asynchronously from within downshift (so you can't use the itemCount prop. |
| unsetItemCount | function() | this unsets the itemCount which means the item count will be calculated instead by the itemCount prop or based on how many times you call getItemProps. |
| setState | function(stateToSet: object, cb: Function) | This is a general setState function. It uses downshift's internalSetState function which works with control props and calls your onSelect, onChange, etc. (Note, you can specify a type which you can reference in some other APIs like the stateReducer). |

> otherStateToSet refers to an object to set other internal state. It is
> recommended to avoid abusing this, but is available if you need it.

$3

These are values that represent the current state of the downshift component.

| property | type | description |
| ------------------ | ----------------- | ---------------------------------------------- |
| highlightedIndex | number / null | the currently highlighted item |
| inputValue | string / null | the current value of the getInputProps input |
| isOpen | boolean | the menu open state |
| selectedItem | any | the currently selected item input |

$3

As a convenience, the id and itemToString props which you pass to
are available here as well.

Event Handlers

Downshift has a few events for which it provides implicit handlers. Several of
these handlers call event.preventDefault(). Their additional functionality is
described below.

$3

- ArrowDown: if menu is closed, opens it and moves the highlighted index to
defaultHighlightedIndex + 1, if defaultHighlightedIndex is provided, or to
the top-most item, if not. If menu is open, it moves the highlighted index
down by 1. If the shift key is held when this event fires, the highlighted
index will jump down 5 indices instead of 1. NOTE: if the current highlighted
index is within the bottom 5 indices, the top-most index will be highlighted.)

- ArrowUp: if menu is closed, opens it and moves the highlighted index to
defaultHighlightedIndex - 1, if defaultHighlightedIndex is provided, or to
the bottom-most item, if not. If menu is open, moves the highlighted index up
by 1. If the shift key is held when this event fires, the highlighted index
will jump up 5 indices instead of 1. NOTE: if the current highlighted index is
within the top 5 indices, the bottom-most index will be highlighted.)

- Home: if menu is closed, it will not add any other behavior. If menu is
open, the top-most index will get highlighted.

- End: if menu is closed, it will not add any other behavior. If menu is open,
the bottom-most index will get highlighted.

- Enter: if the menu is open, selects the currently highlighted item. If the
menu is open, the usual 'Enter' event is prevented by Downshift's default
implicit enter handler; so, for example, a form submission event will not work
as one might expect (though if the menu is closed the form submission will
work normally). See below for customizing the handlers.

- Escape: will clear downshift's state. This means that highlightedIndex
will be set to the defaultHighlightedIndex and the isOpen state will be
set to the defaultIsOpen. If isOpen is already false, the inputValue
will be set to an empty string and selectedItem will be set to null

$3

You can provide your own event handlers to Downshift which will be called before
the default handlers:

`javascript
const ui = (

{({getInputProps}) => (
{...getInputProps({
onKeyDown: event => {
// your handler code
},
})}
/>
)}

)
`

If you would like to prevent the default handler behavior in some cases, you can
set the event's preventDownshiftDefault property to true:

`javascript
const ui = (

{({getInputProps}) => (
{...getInputProps({
onKeyDown: event => {
if (event.key === 'Enter') {
// Prevent Downshift's default 'Enter' behavior.
event.nativeEvent.preventDownshiftDefault = true

// your handler code
}
},
})}
/>
)}

)
`

If you would like to completely override Downshift's behavior for a handler, in
favor of your own, you can bypass prop getters:

`javascript
const ui = (

{({getInputProps}) => (
{...getInputProps()}
onKeyDown={event => {
// your handler code
}}
/>
)}

)
`

Utilities

$3

Allows reseting the internal id counter which is used to generate unique ids for
Downshift component.

You should never need to use this in the browser. Only if you are running an
universal React app that is rendered on the server you should call
resetIdCounter before every render so that the ids that get
generated on the server match the ids generated in the browser.

`javascript
import {resetIdCounter} from 'downshift';

resetIdCounter()
ReactDOMServer.renderToString(...);
`

React Native

Since Downshift renders it's UI using render props, Downshift supports rendering
on React Native with ease. Use components like , ,
and others inside of your render method to generate awesome
autocomplete, dropdown, or selection components.

$3

- Your root view will need to either pass a ref to getRootProps or call
getRootProps with { suppressRefError: true }. This ref is used to catch a
common set of errors around composite components.
Learn more in getRootProps.
- When using a or , be sure to supply the
keyboardShouldPersistTaps
prop to ensure that your text input stays focus, while allowing for taps on
the touchables rendered for your items.

Advanced React Component Patterns course

Kent C. Dodds has created learning material
based on the patterns implemented in this component. You can find it on various
platforms:

1. egghead.io
2. Frontend Masters
3. YouTube (for free!):
Part 1
and
Part 2

Examples

> 🚨 We're in the process of moving all examples to the
> downshift-examples repo
> (which you can open, interact with, and contribute back to live on
> codesandbox)

> 🚨 We're also in the process of updating our examples from the
> downshift-docs repo which is
> actually used to create our docsite at [downshift-js.com][docsite]). Make sure
> to check it out for the most relevant Downshift examples or try out the new
> hooks that aim to replace Downshift.

Ordered Examples:

If you're just learning downshift, review these in order:

0. basic automplete with getRootProps -
the same as example #1 but using the correct HTML structure as suggested by
ARIA-WCAG.
1. basic autocomplete -
very bare bones, not styled at all. Good place to start.
2. styled autocomplete -
more complete autocomplete solution using emotion for styling and
match-sorter for filtering the items.
3. typeahead -
Shows how to control the selectedItem so the selected item can be one of
your items or whatever the user types.
4. multi-select -
Shows how to create a MultiDownshift component that allows for an array of
selectedItems for multiple selection using a state reducer

Other Examples:

Check out these examples of more advanced use/edge cases:

- dropdown with select by key -
An example of using the render prop pattern to utilize a reusable component to
provide the downshift dropdown component with the functionality of being able
to highlight a selection item that starts with the key pressed.
- using actions -
An example of using one of downshift's actions as an event handler.
- gmail's composition recipients field -
An example of a highly complex autocomplete component featuring asynchronously
loading items, multiple selection, and windowing (with react-virtualized)
- Downshift HOC and Compound Components -
An example of how to implementat compound components with
React.createContext and a downshift higher order component. This is
generally not recommended because the render prop API exported by downshift is
generally good enough for everyone, but there's nothing technically wrong with
doing something like this.

Old Examples exist on [codesandbox.io][examples]:

_🚨 This is a great contribution opportunity!_ These are examples that have not
yet been migrated to
downshift-examples.
You're more than welcome to make PRs to the examples repository to move these
examples over there.
Watch this to learn how to contribute completely in the browser

- Integration with Apollo
- Integration with Redux
- Integration with react-instantsearch
from Algolia
- Material-UI (1.0.0-beta.4) Combobox Using Downshift
- Material-UI (1.0.0-beta.33) Multiple select with autocomplete
- Integration with GenieJS
(learn more about genie here)
- Handling and displaying errors
- Integration with React Router
- Windowing with react-tiny-virtual-list
- Section/option group example
- Integration with fuzzaldrin-plus (Fuzzy matching)
- Dropdown/select implementation with Bootstrap
- Multiple editable tag selection
- Downshift implemented as compound components and a Higher Order Component
(exposes a withDownshift higher order component which you can use to get at
the state, actions, prop getters in a rendered downshift tree).
- Downshift Spectre.css example
- Integration with redux-form
- Integration with react-final-form
- Provider Pattern - how to avoid
prop-drilling if you like to break up your render method into more components
- React Native example
- React VR example
- Multiple checkbox selection

FAQ


How do I avoid the checksum error when server rendering (SSR)?


The checksum error you're seeing is most likely due to the automatically
generated id and/or htmlFor prop you get from getInputProps and
getLabelProps (respectively). It could also be from the automatically
generated id prop you get from getItemProps (though this is not likely as
you're probably not rendering any items when rendering a downshift component on
the server).

To avoid these problems, simply call resetIdCounter before
ReactDOM.renderToString.

Alternatively you could provide your own ids via the id props where you render
:

`javascript
const ui = (
id="autocomplete"
labelId="autocomplete-label"
inputId="autocomplete-input"
menuId="autocomplete-menu"
>
{({getInputProps, getLabelProps}) =>

{/ your UI /}

}

)
`

Inspiration

I was heavily inspired by [Ryan Florence][ryan]. Watch his (free) lesson about
["Compound Components"][compound-components-lecture]. Initially downshift was a
group of compound components using context to communicate. But then [Jared
Forsyth][jared] suggested I expose functions (the prop getters) to get props to
apply to the elements rendered. That bit of inspiration made a big impact on the
flexibility and simplicity of this API.

I also took a few ideas from the code in
[react-autocomplete][react-autocomplete] and [jQuery UI's
Autocomplete][jquery-complete].

You can watch me build the first iteration of downshift on YouTube:

- Part 1
- Part 2

You'll find more recordings of me working on downshift on [my livestream
YouTube playlist][yt-playlist].

Other Solutions

You can implement these other solutions using downshift, but if you'd prefer
to use these out of the box solutions, then that's fine too:

- react-select
- react-autosuggest

Bindings for ReasonML

If you're developing some React in ReasonML, check out the
Downshift` bindings for
that.

Contributors

Thanks goes to these people ([emoji key][emojis]):















































Kent C. Dodds 💻 📖 🚇 ⚠️ 👀 📝 🐛 💡 🤔 📢	Ryan Florence 🤔	Jared Forsyth 🤔 📖	Jack Moore 💡	Travis Arnold 💻 📖	Marcy Sutton 🐛 🤔	Jeremy Gayed 💡
Haroen Viaene 💡	monssef 💡	Federico Zivolo 📖	Divyendu Singh 💡 💻 📖 ⚠️	Muhammad Salman 💻	João Alberto 💻	Bernard Lin 💻 📖
Geoff Davis 💡	Anup 📖	Ferdinand Salis 🐛 💻	Kye Hohenberger 🐛	Julien Goux 🐛 💻 ⚠️	Joachim Seminck 💻	Jesse Harlin 🐛 💡
Matt Parrish 🔧 👀	thom 💻	Vu Tran 💻	Codie Mullins 💻 💡	Mohammad Rajabifard 📖 🤔	Frank Tan 💻	Kier Borromeo 💡
Paul Veevers 💻	Ron Cruz Show more