chakra-react-select v6

This component is a wrapper for the popular react component React Select made using the UI library Chakra UI.

[!IMPORTANT]

This version of Chakra React Select is updated for Chakra UI v3 which works exclusively with React version 18 or above. Chakra React Select v5, which is compatible with Chakra UI v2, will be maintained for the foreseeable future. If you're still using Chakra UI v2 check the docs for chakra-react-select v5 here.

| Light Mode | Dark Mode | | :-------------------------------------------------: | :-----------------------------------------------: | | | |

Check out the demo here:

[!NOTE]

Before leaving an issue on this project, remember that this is just a wrapper for react-select, not a standalone package. A large percentage of the questions people have end up being about how react-select itself works, so please read through their documentation to familiarize yourself with it! https://react-select.com/home

Contents

• Usage
• Extra Props
  • size
  • tagColorPalette
  • tagVariant
  • invalid / readOnly
  • focusRingColor
  • selectedOptionStyle
  • selectedOptionColorPalette
  • variant
• Styling
  • chakraStyles
    • Caveats
    • Examples
  • Theme Styles
  • className
• TypeScript Support
• Customizing Components
  • Custom LoadingIndicator (Chakra Spinner)
• useChakraSelectProps
• Usage with React Form Libraries
  • react-hook-form
  • formik
• Templates

Usage

To use this package, you'll need to have @chakra-ui/react@3 set up like in the guide in their docs.

npm i @chakra-ui/react @emotion/react
# ...or...
yarn add @chakra-ui/react @emotion/react

After Chakra UI is set up, install this package from NPM:

npm i chakra-react-select
# ...or...
yarn add chakra-react-select

Once installed, you can import the base select package, the async select, the creatable select or the async creatable select like so:

import {
  AsyncCreatableSelect,
  AsyncSelect,
  CreatableSelect,
  Select,
} from "chakra-react-select";
// ...or...
const {
  AsyncCreatableSelect,
  AsyncSelect,
  CreatableSelect,
  Select,
} = require("chakra-react-select");

All exports, including types, from the original react-select package are also exported from this package, so you can import any of them if you need them. The only exception is the root Select components.

Implementing this component in your application should be almost identical to how you'd normally use react-select. It will accept all of the props that the original package does, with a few additions and exceptions listed below. So if you have a question on basic usage, your best bet is to check the original docs or google "How to (some functionality) with react-select" and just swap out react-select with chakra-react-select in your code.

Extra Props

All of the props from the original react-select package are also available in this package, with a few exceptions. There are also some extra props that have been added to make this component behave/appear more like the built-in Chakra UI components.

There are examples of all of the extra props below included in the demo here.

size — Options: ResponsiveValue<"sm" | "md" | "lg"> — Default: md

You can pass the size prop with either sm, md, or lg. These will reflect the sizes available on the Chakra <Input /> component (except for xs because it's too small to work). Alternatively, you can pass a responsive style array or object of size values to allow it to change depending on your theme's breakpoints.

If no size is passed, it will default to defaultVariants.size from the theme for Chakra's Select component. If your component theme for Select is not modified, it will be md.

return (
  <>
    <Select size="sm" />
    <Select size="md" /> {/* Default */}
    <Select size="lg" />
  </>
);

---

tagColorPalette

You can pass the tagColorPalette prop to the select component to change all of the selected options tags' colors. You can view the whole list of available color palettes in the Chakra docs, or if you have a custom color palette, any of the custom color names in that will be available instead.

Alternatively, you can add the colorPalette key to any of your options objects and it will only style that option when selected.

return (
  <Select
    {/* The global tag color palette */}
    tagColorPalette="purple"
    options={[
      {
        label: "I am red",
        value: "i-am-red",
        colorPalette: "red", // The option color palette overrides the global
      },
      {
        label: "I fallback to purple",
        value: "i-am-purple",
      },
    ]}
  />
);

---

tagVariant — Options: subtle | solid | outline — Default: subtle

You can pass the tagVariant prop with either subtle, solid, or outline (default is subtle). These will reflect the variant prop available on the Chakra <Tag /> component. Alternatively, if you have added any custom variants to your theme, you can use those instead.

Alternatively, you can add the variant key to any of your options objects and it will only style that option when selected. This will override the tagVariant prop on the select if both are set

return (
  <Select
    {/* The global variant */}
    tagVariant="solid"
    options={[
      {
        label: "I have the outline style",
        value: "i-am-outlined",
        variant: "outline", // The option variant overrides the global
      },
      {
        label: "I fallback to the global `solid`",
        value: "i-am-solid",
      },
    ]}
  />
);

---

invalid — Default: false | readOnly - Default: false

You can pass invalid to the select component to style it like the Chakra Input is styled when it receives the same prop. Alternatively, you can pass readOnly to make the component non-interactive in the same way Chakra's Input does.

You can pass also pass invalid, disabled, readOnly, or required into a wrapping Field.Root (or Field if using the snippet) to achieve the same result as passing these props into the Select component. However, if you pass these props into the Select component itself, that will override the props passed into the Field.Root.

In the migration to [Chakra v3](https://www.chakra-ui.