chakra-react-select

chakra-react-select wraps the popular React Select library so it renders using Chakra UI’s design tokens, recipes, and theming system instead of bespoke CSS. Rather than reimplementing dropdown behavior, it forwards nearly every prop from react-select untouched and layers in Chakra-specific extras — size, variant, tagColorPalette, tagVariant, selectedOptionStyle, invalid/readOnly, and a chakraStyles prop that mirrors react-select’s styles API but outputs Chakra SystemStyleObjects instead of raw CSS-in-JS.

Four components are exported — Select, AsyncSelect, CreatableSelect, and AsyncCreatableSelect — matching react-select’s own composition model, plus a useChakraSelectProps hook for merging Chakra-aware defaults into a raw react-select instance or a wrapped component like react-google-places-autocomplete. As of v6 it targets Chakra UI v3 and React 18+ exclusively, with a maintained v5 branch retained for teams still on Chakra UI v2.

What You Get

• Four ready-to-use components — Select, AsyncSelect, CreatableSelect, AsyncCreatableSelect — each a drop-in replacement for their react-select equivalents.
• A chakraStyles prop for per-component style overrides using Chakra’s SystemStyleObject and theme tokens instead of raw CSS-in-JS.
• Automatic Field.Root integration for invalid, disabled, readOnly, and required states, matching Chakra’s native form components.
• The useChakraSelectProps hook for applying the same Chakra defaults to a raw react-select instance or a third-party wrapper.
• Full TypeScript support, including module-augmented react-select prop types and exported types for every custom prop and component.

Common Use Cases

• Adding themed multi-select tag inputs to a Chakra-based form.
• Wiring an async remote-data select (user search, address autocomplete) into a Chakra UI app.
• Standardizing dropdown/select styling across a design system already built on Chakra recipes.
• Integrating validated selects with react-hook-form or Formik via Controller/useController.

Under The Hood

Architecture The package is structured as a thin adapter layer: src/index.ts is the sole public entry point, re-exporting four wrapper components (select/select.tsx, select/creatable-select.tsx, select/async-select.tsx, select/async-creatable-select.tsx) plus a shared use-chakra-select-props.ts hook that performs all of the actual prop-merging work. Each select component is a near-identical forwardRef wrapper that delegates entirely to useChakraSelectProps(props) to normalize and inject Chakra-specific values (size, invalid, readOnly, selectedOptionStyle, etc.), then spreads the result onto the underlying react-select primitive. The chakra-components/ directory holds one file per react-select sub-component slot (control.tsx, menu.tsx, multi-value.tsx, single-value.tsx, placeholder.tsx, containers.tsx, input.tsx, icons.tsx), each overriding react-select’s default rendering with Chakra primitives. use-chakra-select-props.ts also reads Chakra’s useFieldContext() to inherit invalid/disabled/readOnly/required from a wrapping Field.Root. The library’s core mechanism is TypeScript module augmentation of react-select’s own Props type (declared in index.ts) combined with runtime prop injection, rather than forking react-select’s internals — meaning all four exported components share one source of truth and would break identically if that shared layer changed.

Tech Stack A TypeScript project built with tsup (dual CJS/ESM output, generated .d.ts, ES2019 target), depending on react-select as its sole runtime dependency and treating @chakra-ui/react, next-themes, and react as peer dependencies. Uses a pnpm workspace (core package plus a Vite-based demo app), oxlint in typed mode with the react/react-perf/jsx-a11y/unicorn/promise/vitest plugin set plus oxfmt for formatting instead of ESLint/Prettier, vitest with jsdom and @testing-library/react for tests, and @arethetypeswrong/cli plus publint to verify package exports and publishing correctness before release.

Code Quality The test suite is extensive and unusually well-documented: over 5,000 lines across seven files and roughly 90 tests in 17 describe blocks, explicitly ported from react-select’s own upstream test suite with comments instructing maintainers how to re-diff and port future upstream changes; Chakra-specific behavior gets its own dedicated file. The vitest setup file documents and works around several jsdom limitations (CSS parsing, matchMedia) rather than silently suppressing them. CI runs the suite across two Node versions, plus separate typed-lint, type-check, and package-export/publish-lint steps, giving strong confidence the published artifact matches what’s tested.

API Design The public API is designed to be a near drop-in replacement for react-select — same four component shapes, same prop names, same styling-function signature — so migration cost from plain react-select is low. Boilerplate for form validation is reduced by reading invalid/disabled/readOnly/required directly from a wrapping Chakra Field.Root instead of requiring them to be re-passed on every select. Every added prop carries inline JSDoc linking back to both the package’s own README section and the relevant Chakra UI docs page, and the README itself runs to roughly 1,150 lines with live CodeSandbox/StackBlitz demos for nearly every feature.