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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Select
✓ import Select from 'chakra-react-select';
✗ const Select = require('chakra-react-select')
The primary default export for a standard select component. ESM-only usage is recommended.
CreatableSelect
✓ import { CreatableSelect } from 'chakra-react-select';
✗ import CreatableSelect from 'chakra-react-select/CreatableSelect';
Named export for a select component that allows users to create new options. Ensure named import syntax.
AsyncSelect
✓ import { AsyncSelect } from 'chakra-react-select';
✗ import { AsyncSelect } from 'chakra-react-select/async';
Named export for a select component that loads options asynchronously. Always use named import from the root.
ChakraStylesConfig
✓ import { ChakraStylesConfig } from 'chakra-react-select';
Type import for customizing the internal Chakra UI styles of the select components. Only for TypeScript.
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.
import React, { useState } from 'react';
import Select from 'chakra-react-select';
import { ChakraProvider, extendTheme } from '@chakra-ui/react';
const theme = extendTheme({
colors: {
brand: {
50: '#E6FFFA',
100: '#B2F5EA',
200: '#81E6D9',
300: '#4FD1C5',
400: '#38B2AC',
500: '#319795',
600: '#2C7A7B',
700: '#285E61',
800: '#234E52',
900: '#1D4044'
}
}
});
interface Option {
value: string;
label: string;
}
const options: Option[] = [
{ value: 'apple', label: 'Apple' },
{ value: 'banana', label: 'Banana' },
{ value: 'cherry', label: 'Cherry' }
];
function App() {
const [selectedValue, setSelectedValue] = useState<Option | null>(null);
return (
<ChakraProvider theme={theme}>
<div style={{ padding: '20px', maxWidth: '400px', margin: 'auto' }}>
<Select
name="fruits"
options={options}
placeholder="Select a fruit..."
closeMenuOnSelect={true}
selectedOptionColorScheme="brand"
onChange={(newValue) => {
setSelectedValue(newValue as Option);
console.log('Selected value:', newValue);
}}
value={selectedValue}
/>
</div>
</ChakraProvider>
);
}
export default App;
Debug
Known issues
breakingVersion 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.fixEnsure your project's `@chakra-ui/react` dependency is `3.x`. Refer to the Chakra UI v3 migration guide for necessary changes in your application.
affects: >=6.0.0
breakingThe 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.fixExplicitly 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.
affects: >=5.1.0 <6.0.0, >=6.0.0
breakingIn 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.fixVerify 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.
affects: >=6.1.0
breakingThe `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.fixTo achieve similar custom behavior, implement a custom `MultiValueRemove` component for `react-select` by passing it via the `components` prop.
affects: >=5.0.1 <6.0.0, >=6.0.0
gotchaStrict 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.fixAlways 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.
affects: >=5.0.0
Errors
Common errors & fixes
Error: @chakra-ui/react@2.x is not compatible with chakra-react-select@6.x
Using chakra-react-select v6 with an older version of Chakra UI (v2.x or earlier).
fixUpgrade your `@chakra-ui/react` dependency to `3.x` to match the requirements of `chakra-react-select` v6.
TypeError: Cannot read properties of undefined (reading 'styles') in Select
Attempting to directly use the `styles` prop from `react-select` without adapting it for Chakra UI, or an incorrect `chakraStyles` configuration.
fixUse the `chakraStyles` prop for all styling customizations, which correctly integrates with Chakra UI's theme and style props. Avoid using `styles` directly.
Property 'value' does not exist on type 'IntrinsicAttributes & SelectProps<Option, boolean, GroupBase<Option>>'
TypeScript error often due to incorrect type definitions for options or the `value` prop, or missing generic types for the `Select` component.
fixEnsure 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. Audit
Dependencies
reactrequiredCore React library for UI component rendering.
@chakra-ui/reactrequiredThe underlying UI component library for styling and primitives.
next-themesoptionalOptional integration for theme management and dark mode support in Next.js applications.
react-selectrequiredThe foundational select component library that chakra-react-select wraps.