downshift

library9.3.2jsnpmunverified

Downshift is a set of React primitives designed to build highly accessible and flexible autocomplete, combobox, and select dropdown components. It provides stateful logic and ARIA-compliant attributes without dictating UI. The library currently ships with version 9.3.2 and maintains an active release cadence, with bug fixes and minor features released frequently. Key differentiators include its focus on WAI-ARIA compliance, offering both modern React Hooks (like `useCombobox`, `useSelect`, and `useTagGroup`) and a legacy render prop component (`Downshift`). The hooks are the recommended approach as they support the latest ARIA 1.2 combobox patterns, offering superior accessibility compared to the older `Downshift` component which is slated for eventual removal. Downshift prioritizes developer freedom by providing only the necessary logic, allowing users to fully customize the visual presentation.

llm-agents ai-ml

npm install downshift

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DOWNSHIFT

downshift

llm-agentsjavascriptv9.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useCombobox

✓ import { useCombobox } from 'downshift';

✗ const { useCombobox } = require('downshift');

ESM is the primary export since v3. CommonJS `require` might work with transpilers but is generally discouraged for modern React projects.

useSelect

✓ import { useSelect } from 'downshift';

✗ import useSelect from 'downshift';

`useSelect` is a named export. Attempting a default import will result in an undefined value.

Downshift

✓ import { Downshift } from 'downshift';

✗ import Downshift from 'downshift';

The `Downshift` render prop component is deprecated in favor of hooks like `useCombobox` and `useSelect`. While still available, new implementations should use the hooks.

useTagGroup

✓ import { useTagGroup } from 'downshift';

Introduced in v9.2.0, `useTagGroup` is a named export for building multi-select or tag input components.

This example demonstrates how to create an accessible combobox component using the `useCombobox` hook, including filtering and selection logic.

import React, { useState } from 'react'; import { useCombobox } from 'downshift'; const items = ['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']; function MyCombobox() { const [inputItems, setInputItems] = useState(items); const { isOpen, getToggleButtonProps, getLabelProps, getMenuProps, getInputProps, getComboboxProps, highlightedIndex, getItemProps, selectedItem, } = useCombobox({ items: inputItems, onSelectedItemChange: ({ selectedItem }) => { console.log('Selected item:', selectedItem); }, onInputValueChange: ({ inputValue }) => { setInputItems( items.filter((item) => item.toLowerCase().startsWith(inputValue?.toLowerCase() ?? '') ) ); }, }); return ( <div> <label {...getLabelProps()}>Choose your favorite fruit:</label> <div {...getComboboxProps()}> <input {...getInputProps()} /> <button type="button" {...getToggleButtonProps()}> Toggle Menu </button> </div> <ul {...getMenuProps()}> {isOpen && inputItems.map((item, index) => ( <li key={`${item}${index}`} {...getItemProps({ item, index })} style={{ backgroundColor: highlightedIndex === index ? 'lightgray' : 'white', fontWeight: selectedItem === item ? 'bold' : 'normal', }} > {item} </li> ))} </ul> </div> ); } // Example of how to render it (assuming a React root exists) // import ReactDOM from 'react-dom/client'; // const root = ReactDOM.createRoot(document.getElementById('root')); // root.render(<MyCombobox />);

Debug

Known issues

deprecatedThe `Downshift` render prop component is officially deprecated. Users are strongly encouraged to migrate to the `useCombobox` or `useSelect` hooks for new implementations and existing projects.

fix

Migrate your components to use `useCombobox` or `useSelect`. Refer to the official migration guide for v7 and specific hook documentation.

affects: >=7.0.0

breakingVersion 7 introduced significant breaking changes, particularly in how ARIA attributes are handled and the API for the `useCombobox` and `useSelect` hooks, aligning with ARIA 1.2 patterns.

fix

Review the v7 migration guide on the official Downshift website. Many props and return values from the hooks were updated or renamed.

affects: >=7.0.0 <9.0.0

gotchaDownshift is a headless UI library, meaning it provides only the logic and accessibility attributes, not any default styling. You are responsible for all visual styling.

fix

Plan to implement all CSS/styling yourself. The library offers no built-in styles.

affects: >=1.0.0

breakingThe package now explicitly supports CJS and ESM extensions, which might affect older bundler configurations or custom module resolution setups.

fix

Ensure your bundler (e.g., Webpack, Rollup) is configured to correctly resolve `package.json` 'exports' field and handle both CJS and ESM modules. Most modern setups should work out-of-the-box.

affects: >=9.3.0

gotchaIncorrectly managing the `items` prop in `useCombobox` or `useSelect`, especially with asynchronous data or complex filtering, can lead to unexpected UI behavior or performance issues.

fix

Ensure `items` is a stable reference or memoized if it's derived from state. Update `items` efficiently using `onInputValueChange` or similar callbacks to control filtering logic.

affects: >=7.0.0

Errors

Common errors & fixes

TypeError: (0 , downshift__WEBPACK_IMPORTED_MODULE_0__.useCombobox) is not a function

Attempting to `require` the module in a CommonJS context or using an outdated bundler that doesn't correctly handle ESM exports.

fix

Ensure you are using `import { useCombobox } from 'downshift';` in an ESM-compatible environment. If using a CommonJS file, ensure your build setup correctly transpiles or resolves ESM imports. Check bundler configuration for module resolution.

Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined.

This often occurs when trying to render the `Downshift` component, but it was imported incorrectly, or a hook was attempted to be rendered directly.

fix

Verify that `import { Downshift } from 'downshift';` is correct if you are still using the render prop component, or ensure you are calling the `useCombobox`/`useSelect` hooks within a functional React component, not rendering the hook itself.

Warning: The 'items' array passed to Downshift is changing. This can cause issues with component stability. Please consider memoizing the 'items' array or providing a stable reference.

The `items` array provided to `useCombobox` or `useSelect` is being re-created on every render, leading to unnecessary re-renders and potential performance degradation.

fix

Memoize your `items` array using `React.useMemo` if it's derived from other state or props, or ensure it's defined outside the component render function if it's static data.

Upgrade

Version history

9.3.2latest on npm

Audit

Dependencies

reactrequiredPeer dependency for all Downshift components and hooks.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/downshift-js/downshift ↗

packagehttps://www.npmjs.com/package/downshift ↗

homepagehttps://www.downshift-js.com ↗