{"id":10617,"library":"chakra-react-select","title":"Chakra React Select","description":"chakra-react-select is a comprehensive wrapper that integrates the popular `react-select` component library with Chakra UI, providing accessible and customizable dropdown, combobox, and multi-select inputs. It is currently in version 6.1.1 and actively maintained, with frequent releases addressing bug fixes, dependency updates, and new features. The library closely follows major versions of Chakra UI, with v6 specifically introducing compatibility for Chakra UI v3. It differentiates itself by seamlessly blending the extensive feature set and customization capabilities of `react-select` with Chakra UI's styling system and accessibility principles, offering a unified developer experience. It also provides built-in support for theme integration, including color palettes and dark mode with `next-themes`.","status":"active","version":"6.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/csandman/chakra-react-select","tags":["javascript","accessibility","chakra","chakra-ui","combobox","dropdown","input","listbox","menu","typescript"],"install":[{"cmd":"npm install chakra-react-select","lang":"bash","label":"npm"},{"cmd":"yarn add chakra-react-select","lang":"bash","label":"yarn"},{"cmd":"pnpm add chakra-react-select","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core React library for UI component rendering.","package":"react","optional":false},{"reason":"The underlying UI component library for styling and primitives.","package":"@chakra-ui/react","optional":false},{"reason":"Optional integration for theme management and dark mode support in Next.js applications.","package":"next-themes","optional":true},{"reason":"The foundational select component library that chakra-react-select wraps.","package":"react-select","optional":false}],"imports":[{"note":"The primary default export for a standard select component. ESM-only usage is recommended.","wrong":"const Select = require('chakra-react-select')","symbol":"Select","correct":"import Select from 'chakra-react-select';"},{"note":"Named export for a select component that allows users to create new options. Ensure named import syntax.","wrong":"import CreatableSelect from 'chakra-react-select/CreatableSelect';","symbol":"CreatableSelect","correct":"import { CreatableSelect } from 'chakra-react-select';"},{"note":"Named export for a select component that loads options asynchronously. Always use named import from the root.","wrong":"import { AsyncSelect } from 'chakra-react-select/async';","symbol":"AsyncSelect","correct":"import { AsyncSelect } from 'chakra-react-select';"},{"note":"Type import for customizing the internal Chakra UI styles of the select components. Only for TypeScript.","symbol":"ChakraStylesConfig","correct":"import { ChakraStylesConfig } from 'chakra-react-select';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport Select from 'chakra-react-select';\nimport { ChakraProvider, extendTheme } from '@chakra-ui/react';\n\nconst theme = extendTheme({\n  colors: {\n    brand: {\n      50: '#E6FFFA',\n      100: '#B2F5EA',\n      200: '#81E6D9',\n      300: '#4FD1C5',\n      400: '#38B2AC',\n      500: '#319795',\n      600: '#2C7A7B',\n      700: '#285E61',\n      800: '#234E52',\n      900: '#1D4044'\n    }\n  }\n});\n\ninterface Option {\n  value: string;\n  label: string;\n}\n\nconst options: Option[] = [\n  { value: 'apple', label: 'Apple' },\n  { value: 'banana', label: 'Banana' },\n  { value: 'cherry', label: 'Cherry' }\n];\n\nfunction App() {\n  const [selectedValue, setSelectedValue] = useState<Option | null>(null);\n\n  return (\n    <ChakraProvider theme={theme}>\n      <div style={{ padding: '20px', maxWidth: '400px', margin: 'auto' }}>\n        <Select\n          name=\"fruits\"\n          options={options}\n          placeholder=\"Select a fruit...\"\n          closeMenuOnSelect={true}\n          selectedOptionColorScheme=\"brand\"\n          onChange={(newValue) => {\n            setSelectedValue(newValue as Option);\n            console.log('Selected value:', newValue);\n          }}\n          value={selectedValue}\n        />\n      </div>\n    </ChakraProvider>\n  );\n  }\n\nexport default App;","lang":"typescript","description":"This quickstart demonstrates a basic Chakra `Select` component with a list of fruit options, showcasing state management for selection and custom color scheme integration within a Chakra UI provider."},"warnings":[{"fix":"Ensure your project's `@chakra-ui/react` dependency is `3.x`. Refer to the Chakra UI v3 migration guide for necessary changes in your application.","message":"Version 6.0.0 introduces fundamental breaking changes to align with Chakra UI v3. Projects using older versions of Chakra UI (v1 or v2) must upgrade their Chakra UI dependency to v3 before upgrading to chakra-react-select v6.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Explicitly set the `menuPlacement` prop to `'bottom'` or `'top'` if you require the old fixed behavior, or adjust your layout to accommodate the new auto-flipping behavior.","message":"The default `menuPlacement` property changed from a static position (e.g., 'bottom') to `'auto'` in v5.1.0 to match Chakra UI's popover behavior. This can affect layout if your application relied on the previous fixed placement.","severity":"breaking","affected_versions":">=5.1.0 <6.0.0, >=6.0.0"},{"fix":"Verify the visual appearance of selected options after upgrading. If colors are incorrect, adjust your Chakra UI theme's semantic tokens or override the `chakraStyles` for `option` to specify explicit colors.","message":"In v6.1.0, the `selectedOptionColorPalette` now uses semantic tokens (`colorPalette.solid` and `colorPalette.contrast`) instead of direct numeric indices (`.300`, `.500`) for selected option background and text colors. This may alter the appearance of selected options.","severity":"breaking","affected_versions":">=6.1.0"},{"fix":"To achieve similar custom behavior, implement a custom `MultiValueRemove` component for `react-select` by passing it via the `components` prop.","message":"The `isFixed` attribute on options, previously used to remove the tag close button, was deprecated and then fully removed in v5.0.1. Components relying on this prop will no longer function as expected.","severity":"breaking","affected_versions":">=5.0.1 <6.0.0, >=6.0.0"},{"fix":"Always ensure your project's `package.json` dependencies for `react` (18.x || 19.x), `@chakra-ui/react` (3.x), and `react-select` (latest 5.x) fall within the specified peer dependency ranges. Use `npm install --legacy-peer-deps` or `yarn add --skip-peer-deps` as a temporary workaround only if you understand the risks.","message":"Strict peer dependency ranges are enforced for `react`, `@chakra-ui/react`, and `react-select`. Mismatched versions can lead to runtime errors, styling issues, or build failures.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your `@chakra-ui/react` dependency to `3.x` to match the requirements of `chakra-react-select` v6.","cause":"Using chakra-react-select v6 with an older version of Chakra UI (v2.x or earlier).","error":"Error: @chakra-ui/react@2.x is not compatible with chakra-react-select@6.x"},{"fix":"Use the `chakraStyles` prop for all styling customizations, which correctly integrates with Chakra UI's theme and style props. Avoid using `styles` directly.","cause":"Attempting to directly use the `styles` prop from `react-select` without adapting it for Chakra UI, or an incorrect `chakraStyles` configuration.","error":"TypeError: Cannot read properties of undefined (reading 'styles') in Select"},{"fix":"Ensure your options array adheres to the `react-select` expected format (`{ value: string; label: string; }`) and provide generic types to the `Select` component, e.g., `<Select<Option, false> ... />` for single select or `<Select<Option, true> ... />` for multi-select.","cause":"TypeScript error often due to incorrect type definitions for options or the `value` prop, or missing generic types for the `Select` component.","error":"Property 'value' does not exist on type 'IntrinsicAttributes & SelectProps<Option, boolean, GroupBase<Option>>'"}],"ecosystem":"npm"}