Library / SDK
downshift-js/downshift avatar
downshift-js/downshift

downshift: headless React primitives for accessible comboboxes and selects

🏎 A set of primitives to build simple, flexible, WAI-ARIA compliant React autocomplete, combobox or select dropdown components.

12,301 stars931 forksJavaScriptMIT

At a glance

What is it?
downshift is a set of React hooks and a render-prop component that supply the state and ARIA wiring for autocomplete, combobox and select UIs while you keep control of the markup. The hooks target the ARIA 1.2 combobox pattern; the older Downshift component does not, and the maintainers say it will be removed once the hooks mature.
Who is it for?
Use downshift if you need WAI-ARIA compliant combobox or select behaviour but your design system will not accept a prebuilt widget, and start with useCombobox or useSelect rather than the Downshift component. Do not adopt it if you want a finished styled dropdown out of the box, or if you are building on the legacy component and cannot migrate, since the README states it will be removed once the hooks mature.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 6 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • downshift-js/downshift12,301 ★ · -3
Star history
Repository2026-09-222026-11-15
downshift-js/downshift12.3k12.3k

-3 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What downshift solves, and who it is actually for

Building a dropdown that works with a keyboard and a screen reader is mostly bookkeeping: tracking which option is highlighted, keeping aria-activedescendant pointed at the right element, deciding whether Escape closes the menu or clears the input, and announcing changes to assistive technology. downshift takes that bookkeeping and hands it back as props you spread onto your own elements.

The README frames the problem directly: you need an autocomplete, combobox or select experience, you want it accessible, and you want it simple and flexible enough for your own use cases. The audience is therefore teams with an existing design system, or with a dropdown that looks nothing like a standard widget. If your component library already ships an accessible select, downshift adds a dependency without removing work.

The repository is not archived and the last push was on 2026-06-30, the same day as the v9.4.0 release. That is recent enough that the project is not dormant, but the README itself notes a split: the hooks are described as actively maintained and improved, while the component is described as something that will be removed once the hooks mature. Treat those as two products with different futures.

Hooks versus the render-prop component: the same state, two contracts

downshift ships two APIs over one idea. The current one is a set of hooks: useSelect for a custom select, useCombobox for a combobox or autocomplete input, and useTagGroup for a tag group, which the README also suggests for a multiple-selection combobox or select built with tags. Each hook returns the stateful logic for the component, and you render every element yourself.

The older API is the Downshift component, which uses a render prop. Its children function receives prop getters, actions, state and props. Prop getters are the mechanism worth understanding: instead of the library rendering an input or a list item, it hands you a function such as a getter for the input or for an item, and you spread the result onto the element you already wrote. That is how the library attaches handlers and ARIA attributes without owning the DOM.

The README is unusually blunt about which to pick. Both useSelect and useCombobox support the latest WAI-ARIA combobox patterns, which the Downshift component does not, and the hooks moved to the ARIA 1.2 combobox pattern in version 7. The README repeats the recommendation with a warning emoji: use the hooks. That is a rare case of a library telling new users to avoid its own older, still-documented API.

Installing downshift and wiring a first useCombobox

Installation is a single npm command. The README states the module is distributed via npm and should be installed as one of your project's dependencies, and it notes that the package also depends on react, which you are expected to provide yourself.

bash
npm install --save downshift

The README on the repository page covers the Downshift component; each hook has its own README page, reachable from the hooks page or the documentation site at downshift-js.com. That split matters, because the props documented on the main page are the component's, not the hooks'. For a first real use, import useCombobox, pass your items and an itemToString, then spread the returned getters onto your own input, label, menu and item elements. The hook's own README is the place to copy the exact prop names from; the component's prop-getter pattern, described on this page, is the shape you will follow.

What you should see is a plain input and a plain list. The library adds the roles, the aria attributes, the keyboard handling and the open and highlight state. Nothing is styled, and no element is created for you, which is the whole point.

Control props, stateReducer and the cost of owning the state

downshift is uncontrolled by default and controlled when you say so. The component's prop list includes initialSelectedItem, initialInputValue, initialHighlightedIndex and initialIsOpen for the uncontrolled case, and selectedItem, inputValue, highlightedIndex and isOpen as control props for the controlled case. There are also defaultHighlightedIndex and defaultIsOpen, which set the value the state resets to rather than the initial value.

The more interesting lever is stateReducer. It sits in the basic props, next to children, itemToString and onChange, which tells you the maintainers consider it part of the core contract rather than an escape hatch. It intercepts state changes before they are applied, and the README exposes stateChangeTypes so you can branch on which interaction caused the change. That is how you implement behaviour the library does not ship, such as keeping the menu open after a selection or refusing to highlight an item.

The cost is that you now own a state machine you did not write. Every reducer branch you add is code the library's tests do not cover, and the interaction between your branch and the next version's internal changes is on you. For teams that only need a standard combobox, the reducer is dead weight you will never open.

Where downshift is the wrong choice

The clearest limitation is stated by the project itself: the Downshift component does not support the latest ARIA combobox patterns, and the README says it will be removed completely once the hooks become mature. If you have an existing codebase on the component and no appetite for the version 7 migration, you are maintaining against a documented end of life with no removal date given.

The second limitation is the headless design. downshift renders nothing, so it solves accessibility wiring and gives you no visual component, no default styles and no positioning. Menus that must flip above the input, escape an overflow container or survive a scroll need a positioning library or your own logic; the component's prop list includes scrollIntoView and environment, which hints at the browser assumptions involved.

There is also a React Native path. The package exposes a react-native entry point in package.json and the README has a React Native section with a Gotchas subsection, so the support exists, but it is a separate build with its own caveats rather than the default experience. If your target is native, read that section before you plan the work.

How downshift differs from a batteries-included combobox

The obvious alternative is a component library that ships a finished combobox, such as the select and autocomplete widgets in a design system like Material UI or Reach UI. The difference is where the flexibility lives. A batteries-included widget renders the DOM for you and exposes props for the variations its authors anticipated; the README makes this comparison explicitly, saying downshift differs from solutions that render things for their use case and then expose many options for extensibility, which it argues produces a bigger API that is less flexible.

That trade is real in both directions. With a prebuilt widget you get markup, styles and positioning that already work together, and you accept its DOM structure. With downshift you get the ARIA behaviour and the state, and you supply everything else. If your design calls for a combobox that looks like nothing in the library, downshift is less work than overriding a widget's internals. If your design is close to a standard widget, it is more work.

A second alternative is writing the combobox yourself against the WAI-ARIA authoring practices. The README links to the ARIA combobox and select examples, so the specification is the same source downshift follows. The difference is that you would be reimplementing the keyboard model and the state transitions, and version 7 of downshift already did the work of moving to the ARIA 1.2 pattern, with a migration guide documenting the changes.

Maintenance, licensing and what an upgrade costs

The repository is MIT licensed, so you can use, modify and redistribute it, including in commercial and closed-source products, provided the copyright notice and permission notice are kept. That is a permissive licence with no copyleft obligation on your application code. This is a description of the licence text, not legal advice; check the LICENSE file in the repository for the exact terms.

Upgrade cost is concentrated in the version 7 change. The README states the hooks were migrated to the ARIA 1.2 combobox pattern in version 7 and points to a migration guide documenting the changes introduced there. Any code written against the pre-7 hooks is the code most likely to need attention. The current line is 9.x, with v9.4.0 released on 2026-06-30, v9.3.6 and v9.3.5 both on 2026-06-04.

The package publishes a version field of 0.0.0-semantically-released, which means the published version is stamped at release time rather than committed by hand. Build output is split across dist/downshift.cjs.cjs, dist/downshift.esm.mjs and a react-native entry, and the package marks sideEffects as false. If you bundle for the browser, that flag lets a tree-shaking bundler drop the parts you do not import, which matters when you only use one hook.

Editorial conclusion

Use downshift if you need WAI-ARIA compliant combobox or select behaviour but your design system will not accept a prebuilt widget, and start with useCombobox or useSelect rather than the Downshift component. Do not adopt it if you want a finished styled dropdown out of the box, or if you are building on the legacy component and cannot migrate, since the README states it will be removed once the hooks mature. Before committing, read the v7 migration guide and check the stateReducer signature in typings/index.d.ts against the version you install.

Frequently asked questions

How do I use downshift in a React app?

Install it with npm install --save downshift, then import one of the hooks. The README recommends starting with useCombobox for a combobox or autocomplete input and useSelect for a custom select, and spreading the returned prop getters onto your own elements.

Should I use the downshift hooks or the Downshift component?

The README strongly recommends the hooks. It states that useSelect and useCombobox support the latest WAI-ARIA combobox patterns, which the Downshift component does not, and that the component will be removed completely once the hooks become mature.

What is downshift in React?

It is a set of primitives for building WAI-ARIA compliant React autocomplete, combobox and select dropdown components. It provides stateful logic and prop getters, and you remain responsible for rendering everything.

Official sources

  1. downshift-js/downshift on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/downshift-js-downshift.svg)](https://hysenlabs.com/projects/downshift-js-downshift)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/downshift-js-downshift.svg)](https://hysenlabs.com/projects/downshift-js-downshift)

Was this useful?