{"id":13085,"library":"downshift","title":"React Autocomplete and Select Primitives","description":"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.","status":"active","version":"9.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/downshift-js/downshift","tags":["javascript","enhanced input","react","autocomplete","autosuggest","typeahead","dropdown","select","combobox","typescript"],"install":[{"cmd":"npm install downshift","lang":"bash","label":"npm"},{"cmd":"yarn add downshift","lang":"bash","label":"yarn"},{"cmd":"pnpm add downshift","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for all Downshift components and hooks.","package":"react","optional":false}],"imports":[{"note":"ESM is the primary export since v3. CommonJS `require` might work with transpilers but is generally discouraged for modern React projects.","wrong":"const { useCombobox } = require('downshift');","symbol":"useCombobox","correct":"import { useCombobox } from 'downshift';"},{"note":"`useSelect` is a named export. Attempting a default import will result in an undefined value.","wrong":"import useSelect from 'downshift';","symbol":"useSelect","correct":"import { useSelect } from 'downshift';"},{"note":"The `Downshift` render prop component is deprecated in favor of hooks like `useCombobox` and `useSelect`. While still available, new implementations should use the hooks.","wrong":"import Downshift from 'downshift';","symbol":"Downshift","correct":"import { Downshift } from 'downshift';"},{"note":"Introduced in v9.2.0, `useTagGroup` is a named export for building multi-select or tag input components.","symbol":"useTagGroup","correct":"import { useTagGroup } from 'downshift';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { useCombobox } from 'downshift';\n\nconst items = ['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple'];\n\nfunction MyCombobox() {\n  const [inputItems, setInputItems] = useState(items);\n  const { \n    isOpen,\n    getToggleButtonProps,\n    getLabelProps,\n    getMenuProps,\n    getInputProps,\n    getComboboxProps,\n    highlightedIndex,\n    getItemProps,\n    selectedItem,\n  } = useCombobox({\n    items: inputItems,\n    onSelectedItemChange: ({ selectedItem }) => {\n      console.log('Selected item:', selectedItem);\n    },\n    onInputValueChange: ({ inputValue }) => {\n      setInputItems(\n        items.filter((item) =>\n          item.toLowerCase().startsWith(inputValue?.toLowerCase() ?? '')\n        )\n      );\n    },\n  });\n\n  return (\n    <div>\n      <label {...getLabelProps()}>Choose your favorite fruit:</label>\n      <div {...getComboboxProps()}>\n        <input {...getInputProps()} />\n        <button type=\"button\" {...getToggleButtonProps()}>\n          Toggle Menu\n        </button>\n      </div>\n      <ul {...getMenuProps()}>\n        {isOpen &&\n          inputItems.map((item, index) => (\n            <li\n              key={`${item}${index}`}\n              {...getItemProps({ item, index })}\n              style={{\n                backgroundColor:\n                  highlightedIndex === index ? 'lightgray' : 'white',\n                fontWeight: selectedItem === item ? 'bold' : 'normal',\n              }}\n            >\n              {item}\n            </li>\n          ))}\n      </ul>\n    </div>\n  );\n}\n\n// Example of how to render it (assuming a React root exists)\n// import ReactDOM from 'react-dom/client';\n// const root = ReactDOM.createRoot(document.getElementById('root'));\n// root.render(<MyCombobox />);","lang":"typescript","description":"This example demonstrates how to create an accessible combobox component using the `useCombobox` hook, including filtering and selection logic."},"warnings":[{"fix":"Migrate your components to use `useCombobox` or `useSelect`. Refer to the official migration guide for v7 and specific hook documentation.","message":"The `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.","severity":"deprecated","affected_versions":">=7.0.0"},{"fix":"Review the v7 migration guide on the official Downshift website. Many props and return values from the hooks were updated or renamed.","message":"Version 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.","severity":"breaking","affected_versions":">=7.0.0 <9.0.0"},{"fix":"Plan to implement all CSS/styling yourself. The library offers no built-in styles.","message":"Downshift 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The package now explicitly supports CJS and ESM extensions, which might affect older bundler configurations or custom module resolution setups.","severity":"breaking","affected_versions":">=9.3.0"},{"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.","message":"Incorrectly managing the `items` prop in `useCombobox` or `useSelect`, especially with asynchronous data or complex filtering, can lead to unexpected UI behavior or performance issues.","severity":"gotcha","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require` the module in a CommonJS context or using an outdated bundler that doesn't correctly handle ESM exports.","error":"TypeError: (0 , downshift__WEBPACK_IMPORTED_MODULE_0__.useCombobox) is not a function"},{"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.","cause":"This often occurs when trying to render the `Downshift` component, but it was imported incorrectly, or a hook was attempted to be rendered directly.","error":"Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined."},{"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.","cause":"The `items` array provided to `useCombobox` or `useSelect` is being re-created on every render, leading to unnecessary re-renders and potential performance degradation.","error":"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."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}