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, they ended up removing the invalid prop from the Input, Select, and Textarea components themselves in favor of always having the user pass it into the wrapping Field.Root instead. However, it was decided that it wouldn't hurt to keep the prop on this component as well, as users don't always wrap their components in a Field.Root in the first place.

return (
  <>
    {/* This will show up with a red border */}
    <Select invalid />

    {/* This will show up normally but will not be interactive */}
    <Select readOnly />

    {/* This will show up grayed out and will not be interactive */}
    {/* Additionally, it will have a red border and the error message will be shown */}
    <Field
      label="Invalid & Disabled Select"
      invalid
      disabled
      invalidText="This error message shows because of an invalid Field.Root"
    >
      <Select />
    </Field>

    {/* Or here's an example without using the snippet */}
    <Field.Root invalid disabled required>
      <Field.Label>
        Invalid & Disabled Select
        <Field.RequiredIndicator />
      </Field.Label>
      <Select />
      <Field.ErrorText>
        This error message shows because of an invalid Field.Root
      </Field.ErrorText>
    </Field.Root>
  </>
);

focusRingColor

The prop focusRingColor can be passed with Chakra color tokens which will emulate style the control component when focused.

return <Select focusRingColor="blue.600" />;

selectedOptionStyle — Options: color | check — Default: color

You can pass the prop selectedOptionStyle with either "color" or "check". The default option "color" will style a selected option similar to how react-select does it, by highlighting the selected option in the color blue. Alternatively, if you pass "check" for the value, the selected option will be styled like the Chakra UI <Select /> component and include a check icon on the right side of the selected option(s).

return (
  <>
    <Select selectedOptionStyle="color" /> {/* Default */}
    <Select selectedOptionStyle="check" /> {/* Chakra UI Menu Style */}
  </>
);

selectedOptionColorPalette — Default: blue

If you choose to stick with the default selectedOptionStyle="color", you have one additional styling option. If you do not like the default of blue for the highlight color, you can pass the selectedOptionColorPalette prop to change it. This prop will accept any named color from your theme's color palette, and it will use colorPalette.solid for the background, and colorPalette.contrast for the text.

If you'd like to use a custom color palette for this prop, ensure that you have properly set up the custom color, including the solid and contrast semantic tokens, accoring to the official guide.

[!NOTE]

This prop can only be used for named colors from your theme, not arbitrary hex/rgb colors. If you would like to use a specific color for the background that's not a part of your theme, use the chakraStyles prop to customize it (see #99 for an example).

return (
  <>
    <Select selectedOptionColorPalette="blue" /> {/* Default */}
    <Select selectedOptionColorPalette="purple" />
  </>
);

-