Chakra React Select

Common errors

• Error: @chakra-ui/react@2.x is not compatible with chakra-react-select@6.x

  cause Using chakra-react-select v6 with an older version of Chakra UI (v2.x or earlier).
  fix Upgrade 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

  cause Attempting to directly use the `styles` prop from `react-select` without adapting it for Chakra UI, or an incorrect `chakraStyles` configuration.
  fix Use 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>>'

  cause TypeScript error often due to incorrect type definitions for options or the `value` prop, or missing generic types for the `Select` component.
  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.

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• breaking 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.
  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.
• breaking 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.
  Fix: To achieve similar custom behavior, implement a custom `MultiValueRemove` component for `react-select` by passing it via the `components` prop.
• gotcha 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.
  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.

Install

• npm install chakra-react-select npm
• yarn add chakra-react-select yarn
• pnpm add chakra-react-select pnpm

Imports

• Select
  wrong:

  const Select = require('chakra-react-select')

  correct:

  import Select from 'chakra-react-select';

  The primary default export for a standard select component. ESM-only usage is recommended.
• CreatableSelect
  wrong:

  import CreatableSelect from 'chakra-react-select/CreatableSelect';

  correct:

  import { CreatableSelect } from 'chakra-react-select';

  Named export for a select component that allows users to create new options. Ensure named import syntax.
• AsyncSelect
  wrong:

  import { AsyncSelect } from 'chakra-react-select/async';

  correct:

  import { AsyncSelect } from 'chakra-react-select';

  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.

Quickstart

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;