`. It defaults to `ref`. If you're rendering a composite component, `Downshift` checks that `getRootProps` is called and that `refKey` is a prop of the returned composite component. This is done to catch common causes of errors but, in some cases, the check could fail even if the ref is correctly forwarded to the root DOM component. In these cases, you can provide the object `{suppressRefError : true}` as the second argument to `getRootProps` to completely bypass the check.\ **Please use it with extreme care and only if you are absolutely sure that the ref is correctly forwarded otherwise `Downshift` will unexpectedly fail.**\ See [#235](https://github.com/downshift-js/downshift/issues/235) for the discussion that lead to this. #### `getInputProps` This method should be applied to the `input` you render. It is recommended that you pass all props as an object to this method which will compose together any of the event handlers you need to apply to the `input` while preserving the ones that `downshift` needs to apply to make the `input` behave. There are no required properties for this method. Optional properties: - `disabled`: If this is set to true, then no event handlers will be returned from `getInputProps` and a `disabled` prop will be returned (effectively disabling the input). - `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. #### `getLabelProps` This method should be applied to the `label` you render. It is useful for ensuring that the `for` attribute on the `` (`htmlFor` as a react prop) is the same as the `id` that appears on the `input`. If no `htmlFor` is provided (the normal case) then an ID will be generated and used for the `input` and the `label` `for` attribute. There are no required properties for this method. > Note: For accessibility purposes, calling this method is highly recommended. #### `getMenuProps` This method should be applied to the element which contains your list of items. Typically, this will be a `

` or a `

`, 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

{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 = (

`, there is no need to specify this property. It defaults to `ref`. - `aria-label`: By default the input 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 `getInput`. **Please use it with extreme care and only if you are absolutely sure that the ref is correctly forwarded otherwise `useCombobox` will unexpectedly fail.** ### actions These are functions you can call to change the state of the downshift `useCombobox` hook. | property | type | description | | --------------------- | ------------------------- | ----------------------------------------------------- | | `closeMenu` | `function()` | closes the menu | | `openMenu` | `function()` | opens the menu | | `selectItem` | `function(item: any)` | selects the given item | | `setHighlightedIndex` | `function(index: number)` | call to set a new highlighted index | | `setInputValue` | `function(value: string)` | call to set a new value in the input | | `toggleMenu` | `function()` | toggle the menu open state | | `reset` | `function()` | this resets downshift's state to a reasonable default | ### state These are values that represent the current state of the downshift component. | property | type | description | | ------------------ | --------- | --------------------------------- | | `highlightedIndex` | `number` | the currently highlighted item | | `isOpen` | `boolean` | the menu open state | | `selectedItem` | `any` | the currently selected item input | | `inputValue` | `string` | the value in the input | ## 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. ### Default handlers #### Toggle Button - `Click`: If the menu is not displayed, it will open it. Otherwise it will close it. It will additionally move focus on the input in order for screen readers to correctly narrate which item is currently highlighted. If there is already an item selected, the menu will be opened with that item already highlighted. - `Enter`: Has the same effect as `Click`. Button not in the tab order by default. - `Space`: Has the same effect as `Click`. Button not in the tab order by default. #### Input - `ArrowDown`: Moves `highlightedIndex` one position down. When reaching the last option, `ArrowDown` will move `highlightedIndex` to first position. - `ArrowUp`: Moves `highlightedIndex` one position up. When reaching the first option, `ArrowUp` will move `highlightedIndex` to last position. - `Alt+ArrowDown`: If the menu is closed, it will open it, without highlighting any item. - `Alt+ArrowUp`: If the menu is open, it will close it and will select the item that was highlighted. - `CharacterKey`: Will change the `inputValue` according to the value visible in the ``. `Backspace` or `Space` trigger the same event. - `End`: If the menu is open, it will highlight the last item in the list. - `Home`: If the menu is open, it will highlight the first item in the list. - `PageUp`: If the menu is open, it will move the highlight the item 10 positions before the current selection. - `PageDown`: If the menu is open, it will move the highlight the item 10 positions after the current selection. - `Enter`: If there is a highlighted option, it will select it and close the menu. - `Escape`: It will close the menu if open. If the menu is closed, it will clear selection: the value in the `input` will become an empty string and the item stored as `selectedItem` will become `null`. - `Click`: If the menu is closed, it will open it. If the menu is open, it will close it. - `Blur(Tab, Shift+Tab)`: It will close the menu and select the highlighted item, if any. The focus will move naturally to the next/previous element in the Tab order. - `Blur(mouse click outside)`: It will close the menu without selecting any element, even if there is one highlighted. #### Menu - `MouseLeave`: Will clear the value of the `highlightedIndex` if it was set. #### Item - `Click`: It will select the item, close the menu and move focus to the toggle button (unless `defaultIsOpen` is true). - `MouseOver`: It will highlight the item. ### Customizing Handlers You can provide your own event handlers to `useCombobox` which will be called before the default handlers: ```javascript const items = [...] // items here. const {getMenuProps} = useCombobox({items}) const ui = ( /* button, label, ... */

` to the children render prop. These props are called getter props, and their return values are destructured as a set of ARIA attributes and event listeners. Together with the action props and state props, they create all the stateful logic needed for the tag group to implement the list of requirements. Every functionality needed should be provided out-of-the-box: item removal and selection, and left/right arrow movement between items, screen reader support etc. ## Table of Contents - [Usage](#usage) - [Basic Props](#basic-props) - [removeElementDescription](#removeelementdescription) - [onItemsChange](#onitemschange) - [stateReducer](#statereducer) - [Advanced Props](#advanced-props) - [isItemDisabled](#isitemdisabled) - [initialItems](#initialitems) - [initialActiveIndex](#initialactiveindex) - [onActiveIndexChange](#onactiveindexchange) - [onStateChange](#onstatechange) - [activeIndex](#activeindex) - [items](#items) - [id](#id) - [tagGroupId](#taggroupid) - [getTagId](#gettagid) - [environment](#environment) - [stateChangeTypes](#statechangetypes) - [Control Props](#control-props) - [Returned props](#returned-props) - [prop getters](#prop-getters) - [`getTagGroupProps`](#gettaggroupprops) - [`getTagProps`](#gettagprops) - [`getTagRemoveProps`](#gettagremoveprops) - [actions](#actions) - [state](#state) - [Event Handlers](#event-handlers) - [Default handlers](#default-handlers) - [Tag Group](#tag-group) - [Tag](#tag) - [Tag Remove](#tag-remove) - [Customizing Handlers](#customizing-handlers) - [Examples](#examples) ## Usage > [Try it out in the browser][sandbox-example] ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Basic Props This is the list of props that you should probably know about. There are some [advanced props](#advanced-props) below as well. ### removeElementDescription > `string` | defaults to: `"Press Delete or Backspace to remove tag."` An accessible description that gets added to the DOM in an invisible element and gets picked up by screen readers when encountering tags. It should instruct users how to remove tags with the keyboard. Useful for localized messages. ### onItemsChange > `function(changes: object)` | optional, no useful default Called each time the items in state changed. Adding items can be done using `addItem`, while removing items could be done with mouse and keyboard actions. - `changes`: These are the properties that actually have changed since the last state change. This object is guaranteed to contain the `items` property with the newly selected value. This also has a `type` property which you can learn more about in the [`stateChangeTypes`](#statechangetypes) section. This property will be part of the actions that can trigger a `items` change, for example `useTagGroup.stateChangeTypes.FunctionAddItem`. ### stateReducer > `function(state: object, actionAndChanges: object)` | optional **🚨 This is a really handy power feature 🚨** This function will be called each time `useTagGroup` sets its internal state (or calls your `onStateChange` handler for control props). It allows you to modify the state change that will take place which can give you fine grain control over how the component interacts with user updates. It gives you the current state and the state that will be set, and you return the state that you want to set. - `state`: The full current state of useTagGroup. - `actionAndChanges`: Object that contains the action `type`, props needed to return a new state based on that type and the changes suggested by the useTagGroup default reducer. About the `type` property you can learn more about in the [`stateChangeTypes`](#statechangetypes) section. ```javascript import {useTagGroup} from 'downshift' import {items} from './utils' const {getTagGroupProps, getTagProps, getTagRemoveProps, ...rest} = useTagGroup( { initialItems: items.slice(0, 4), stateReducer, }, ) function stateReducer(state, actionAndChanges) { const {type, changes} = actionAndChanges // resets active item to the first when removing an item switch (type) { case useSelect.stateChangeTypes.TagGroupKeyDownBackspace: case useSelect.stateChangeTypes.TagGroupKeyDownDelete: return { ...changes, // default tagGroup new state changes on item removal. activeIndex: changes.items.length === 0 ? -1 : 0, } default: return changes // otherwise business as usual. } } ``` > NOTE: This is only called when state actually changes. You should not attempt > use this to handle events. If you wish to handle events, put your event > handlers directly on the elements (make sure to use the prop getters though! > For example `

_{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} 📖	_{Rick McGavin} 📖	_{Jelle Versele} 💡	_{Brent Ertz} 🤔	_{Justice Mba} 💻 📖 🤔	_{Mark Ellis} 🤔
_{us͡an̸df͘rien͜ds͠} 🐛 💻 ⚠️	_{Robin Drexler} 🐛 💻	_{Arturo Romero} 💡	_yp 🐛 💻 ⚠️	_{Dave Garwacke} 📖	_{Ivan Pazhitnykh} 💻 ⚠️	_{Luis Merino} 📖
_{Andrew Hansen} 💻 ⚠️ 🤔	_{John Whiles} 💻	_{Justin Hall} 🚇	_{Pete Nykänen} 👀	_{Jared Palmer} 💻	_{Philip Young} 💻 ⚠️ 🤔	_{Alexander Nanberg} 📖 💻
_{Pete Redmond} 🐛	_{Nick Lavin} 🐛 💻 ⚠️	_{James Long} 🐛 💻	_{Michael Ball} 🐛 💻 ⚠️	_{CAVALEIRO Julien} 💡	_{Kim Grönqvist} 💻 ⚠️	_Sijie 🐛 💻
_{Dony Sukardi} 💡 💬 💻 ⚠️	_{Dillon Mulroy} 📖	_{Curtis Tate Wilkinson} 💻	_{Brice BERNARD} 🐛 💻	_{Tony Xu} 💻	_{Anthony Ng} 📖	_{S S} 💬 💻 📖 🤔 ⚠️
_{Austin Tackaberry} 💬 💻 📖 🐛 💡 🤔 👀 ⚠️	_{Jean Duthon} 🐛 💻	_{Anton Telesh} 🐛 💻	_{Eric Edem} 💻 📖 🤔 ⚠️	_{Austin Wood} 💬 📖 👀	_{Mark Murray} 🚇	_Gianmarco 🐛 💻
_{Emmanuel Pastor} 💡	_dalehurwitz 💻	_{Bogdan Lobor} 🐛 💻	_{Luke Herrington} 💡	_{Brandon Clemons} 💻	_Kieran 💻	_{Brushedoctopus} 🐛 💻
_{Cameron Edwards} 💻 ⚠️	_{stereobooster} 💻 ⚠️	_{Trevor Pierce} 👀	_{Xuefei Li} 💻	_{Alfred Ringstad} 💻	_{D[oa]vid Weisz} 💻	_{Royston Shufflebotham} 🐛 💻
_{Michaël De Boey} 💻	_Henry 💻	_{Andrew Walton} 🐛 💻 ⚠️	_{Arthur Denner} 💻	_{Cody Olsen} 💻	_{Thomas Ladd} 💻	_lixualinta 💻
_{Jacob Cofman} 💻	_{Joshua Freedman} 💻	_Amy 💡	_{Rogin Farrer} 💻	_{Dmitrii Kanatnikov} 💻	_{Dallon Feldner} 🐛 💻	_{Samuel Fuller Thomas} 💻
_{Ryan Castner} 💻	_{Silviu Alexandru Avram} 🐛 💻 ⚠️	_{Anton Volkov} 💻 ⚠️	_{Keegan Street} 🐛 💻	_{Manuel Dugué} 💻	_{Max Karadeniz} 💻	_{Gonzalo Beviglia} 🐛 💻 👀
_{Brian Kilrain} 🐛 💻 ⚠️ 📖	_{Gerd Zschaler} 💻 🐛	_{Karen Gasparyan} 💻	_{Sergey Korchinskiy} 🐛 💻 ⚠️	_{Edygar Oliveira} 💻 🐛	_epeicher 🐛	_{François Chalifour} 💻 ⚠️ 📦
_{Maxim Malov} 🐛 💻	_{Enrique Piqueras} 🤔	_{Oleksandr Fediashov} 💻 🚇 🤔	_{Mikhail Bashurov} 💻 🐛	_{Joshua Godi} 💻	_{Kanitkorn Sujautra} 🐛 💻	_{Jorge Moya} 💻 🐛
_{Jakub Jastrzębski} 💻	_{Shukhrat Mukimov} 💻	_{Jhonny Moreira} 💻	_stefanprobst 💻 ⚠️	_{Louisa Spicer} 💻 🐛	_{Ryō Igarashi} 🐛 💻	_{Ryan Lue} 📖
_{Mateusz Leonowicz} 💻	_{Dennis Thompson} ⚠️	_{Maksym Boytsov} 💻	_{Sergey Skrynnikov} 💻 ⚠️	_{Vincent Voyer} 📖	_limejoe 💻 🐛	_{Manish Kumar} 💻
_{Anang Fachreza} 📖 💡	_{Nick Deom} 💻 🐛	_{Clément Garbay} 💻	_{Kaimin Huang} 💻 🐛	_{David Welling} 💻 🐛 🤔 🔬	_{chandrasekhar1996} 🐛 💻	_{Brendan Drew} 💻
_{Jean Pan} 💻	_{Tom Jenkinson} 🚇	_{Alice Hendicott} 💻 🐛	_{Zach Davis} 💻 🐛

downshift 🏎