Downshift

Downshift provides two main ways to build accessible autocomplete, combobox, or select components:

1. Hooks (Recommended): A set of React hooks that provide stateful logic. These are actively maintained and support the latest W3C ARIA 1.2 combobox patterns.

   • useSelect: For custom select components.
   • useCombobox: For combobox or autocomplete inputs.
   • useTagGroup: For tag groups or multiple selection components.

2. Downshift Component: A render-prop component that provides logic via a function child. While powerful and flexible, it does not support the latest ARIA patterns and is slated for eventual removal in favor of the hooks.

useMultipleSelection is a React hook designed to manage the stateful logic for accessible multiple selection dropdowns (either a select or a combobox).

It handles:

• Adding and removing items from the selection.
• Navigating between selected items and the dropdown.
• ARIA attributes and event listeners via getter props.
• Accessibility features like aria-live messages for item removal.

It is intended to be used alongside other hooks like useCombobox or useSelect to provide a complete multiple-selection experience.

Downshift allows you to take full control of its state by passing specific props. When these are provided, Downshift treats them as the source of truth (the "controlled" pattern).

The following are control props:

• highlightedIndex: The index that should be highlighted.
• inputValue: The value the input should have.
• isOpen: Whether the menu should be open or closed.
• selectedItem: The currently selected item (can be a single item or an array).

By default, useTagGroup manages its own state for items and activeIndex. However, you can take full control of this state by passing these values as props. This is useful when integrating with external state management like Redux or React Router.

Controlled Props:

• items: The items part of the tag group.
• activeIndex: The index of the item that should be active/focused.

When these props are provided (!== undefined), Downshift will use your values instead of its internal state. You are responsible for updating these values via onStateChange or other handlers to keep the UI in sync.

The Downshift component uses a render prop pattern via its children function. This function receives a downshift object containing state, prop getters, and actions, allowing you to render your own UI while Downshift manages the logic and accessibility.

const ui = (
  <Downshift>
    {downshift => (
      // Use downshift utilities and state here
      <div>{/* your JSX */}</div>
    )}
  </Downshift>
)

const ui = (
  <Downshift>
    {downshift => (
      // use downshift utilities and state here, like downshift.isOpen,
      // downshift.getInputProps, etc.
      <div>{/* more jsx here */}</div>
    )}
  </Downshift>
)

Prop getters are functions that return ARIA attributes and event handlers. You should apply them to your elements to ensure accessibility. It is recommended to pass your own props into the getter function to avoid overriding or being overridden.

Important: getTagProps and getTagRemoveProps are impure functions. They should only be called when you are actually applying the props to an item. Do not call them inside a .map() loop if you might return null before using the result; instead, filter your items first.

// Correct way to use impure prop getters
items
  .filter(shouldRenderItem)
  .map(item => <div {...getTagProps({item})} />)

Downshift provides "prop getters" to apply necessary ARIA attributes and event handlers to your elements. To ensure accessibility and prevent your own props from being overridden, always spread the returned props onto your elements and pass your custom props as an argument to the getter.

Example: getInputProps({ onKeyUp(event) { console.log(event) } })

By default, Downshift manages its own internal state for selectedItems and activeIndex. However, you can switch to a controlled component pattern by passing these state values as props.

When you provide a prop like selectedItems={myState}, Downshift will use your value instead of its internal state. You are then responsible for updating that state, typically by using the onStateChange handler or other state management tools like Redux or React Router.