# Combobox - Page: https://jiguang132.com/resources/chakra-ui/docs/combobox - Resource: Chakra UI (https://jiguang132.com/resources/chakra-ui.md) - All guides: https://jiguang132.com/resources/chakra-ui/docs.md A versatile input component that combines a text input with a listbox, allowing users to filter a list of options and select single or multiple values. Keep query text separate from selected values, distinguish loading/empty/error states, and load selected items for rehydration. See the dedicated practical guide. ## Included icon notices The source viewer includes ICON_ATTRIBUTION.md and original notices for the icon collections used by these examples. Preserve them when redistributing examples; react-icons' wrapper license does not replace individual collection terms. - Lucide: ISC Combine a text input with a list of options for searching, single selection or multiple selection. Input text and selected values are distinct state; a query is not automatically a selected business value. This guide uses native Chakra UI 3.37.0 APIs. ## Setup and structure Complete setup.en.md. The basic example imports `Combobox`, `Portal`, `useListCollection` and `useFilter` from `@chakra-ui/react`. The collection hook manages items; the filter hook provides locale-aware matching. When a server supplies search results, do not silently apply a conflicting local filter. Keep Root, Label, Control and Input, with Trigger and ClearTrigger when needed. The popup uses Positioner, Content, Item and ItemIndicator. Use `Combobox.Empty` for no matches, not for a failed request. ## State and examples `inputValue` / `onInputValueChange` manage query text through `event.inputValue`. `value` / `onValueChange` manage the selected value array. Controlled state requires the application to apply updates, not only pass a fixed value. The inventory retains 28 examples covering multiple selection, custom objects, highlighting, minimum characters, disabled items, validation, forms, virtualization, controlled open state, limits, creating options and nested popovers. Store-based composition uses native `useCombobox` and `Combobox.RootProvider`, not another library's store. ## Async search and rehydration `combobox-with-async-content` and `combobox-rehydrate-value` additionally use `react-use@17.6.1` and a public Star Wars endpoint. JGuang blocks these external requests and preserves their real error behavior with a bilingual restriction notice. This is not a production search backend. The rehydration example starts with `defaultValue: ["C-3PO"]` and calls `combobox.syncSelectedItems()` when collection data arrives. An ID alone does not guarantee a display label; production code must reliably load selected items, not assume that the current query returns them. Check response.ok, cancel or disregard old requests, distinguish loading/error/empty states and debounce where appropriate. Do not send private user queries to public demo services. Resetting the preview does not remove CSP restrictions. ## Acceptance and provenance Test typing, arrows, Enter selection, Escape, clearing, multiple values, no results and failure recovery. Verify active-option accessibility when virtualizing and follow `combobox-open-from-popover` for nested overlays. Retain Chakra themes and provide translated business labels. This is a JGuang practical guide. Original documentation and source are retained in vendor at commit `2e7517745cff2fcde0b8012f136cf99611ff262a`. Successful loading does not prove all search, network or accessibility states are accepted. ## Installation and initialization ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` Initialize ChakraProvider with defaultSystem and Emotion before rendering. Preserve the host React version and inspect peer compatibility. Official npm installation supplies components, not these example source files. Use the resource setup guide for locale, next-themes and framework-specific SSR; copy the selected example source separately from npm installation. ## Complete native usage example This is the actual pinned example, not a generic API mock. Copy its source closure and retain the named export. Additional imports are listed per example below. ```tsx "use client" import { Combobox, Portal, useFilter, useListCollection, } from "@chakra-ui/react" export const ComboboxBasic = () => { const { contains } = useFilter({ sensitivity: "base" }) const { collection, filter } = useListCollection({ initialItems: frameworks, filter: contains, }) return ( filter(e.inputValue)} width="320px" > Select framework No items found {collection.items.map((item) => ( {item.label} ))} ) } const frameworks = [ { label: "React", value: "react" }, { label: "Solid", value: "solid" }, { label: "Vue", value: "vue" }, { label: "Angular", value: "angular" }, { label: "Svelte", value: "svelte" }, { label: "Preact", value: "preact" }, { label: "Qwik", value: "qwik" }, { label: "Lit", value: "lit" }, { label: "Alpine.js", value: "alpinejs" }, { label: "Ember", value: "ember" }, { label: "Next.js", value: "nextjs" }, ] ``` ## All examples and reproduction requirements Names identify demos, not component variant props. Copy every sourceFiles entry for the selected example. The compositions alias denotes local files, not a package. Preserve relative imports or rewrite the alias to your project's actual path. React peers are inspected separately; editor examples retain the coherent pinned Tiptap extension family. ### Basic `combobox-basic` · Named export `ComboboxBasic` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-basic.tsx` ### With Sizes `combobox-with-sizes` · Named export `ComboboxWithSizes` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-sizes.tsx` ### With Variants `combobox-with-variants` · Named export `ComboboxWithVariants` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-variants.tsx` ### With Multiple `combobox-with-multiple` · Named export `ComboboxWithMultiple` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-multiple.tsx` ### With Async Content `combobox-with-async-content` · Named export `ComboboxWithAsyncContent` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 react-use@17.6.1 ``` - `vendor/apps/compositions/src/examples/combobox-with-async-content.tsx` ### With Highlight `combobox-with-highlight` · Named export `ComboboxWithHighlight` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-highlight.tsx` ### Open On Click `combobox-open-on-click` · Named export `ComboboxOpenOnClick` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-open-on-click.tsx` ### With Custom Object `combobox-with-custom-object` · Named export `ComboboxWithCustomObject` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-custom-object.tsx` ### Min Character `combobox-min-character` · Named export `ComboboxMinCharacter` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-min-character.tsx` ### With Field `combobox-with-field` · Named export `ComboboxWithField` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-field.tsx` ### With Form Submit `combobox-with-form-submit` · Named export `ComboboxWithFormSubmit` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-form-submit.tsx` ### With Hook Form `combobox-with-hook-form` · Named export `ComboboxWithHookForm` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 @hookform/resolvers@5.4.0 react-hook-form@7.77.0 zod@4.4.3 ``` - `vendor/apps/compositions/src/examples/combobox-with-hook-form.tsx` ### With Disabled `combobox-with-disabled` · Named export `ComboboxWithDisabled` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-disabled.tsx` ### With Disabled Item `combobox-with-disabled-item` · Named export `ComboboxWithDisabledItem` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-disabled-item.tsx` ### With Input Group `combobox-with-input-group` · Named export `ComboboxWithInputGroup` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 react-icons@5.6.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-input-group.tsx` ### With Invalid `combobox-with-invalid` · Named export `ComboboxWithInvalid` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-invalid.tsx` ### Controlled `combobox-controlled` · Named export `ComboboxControlled` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-controlled.tsx` ### With Store `combobox-with-store` · Named export `ComboboxWithStore` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-store.tsx` ### Open Controlled `combobox-open-controlled` · Named export `ComboboxOpenControlled` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-open-controlled.tsx` ### With Limit `combobox-with-limit` · Named export `ComboboxWithLimit` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-limit.tsx` ### Virtualized `combobox-virtualized` · Named export `ComboboxVirtualized` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 @tanstack/react-virtual@3.14.2 ``` - `vendor/apps/compositions/src/examples/combobox-virtualized.tsx` ### With Links `combobox-with-links` · Named export `ComboboxWithLinks` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 react-icons@5.6.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-links.tsx` ### Rehydrate Value `combobox-rehydrate-value` · Named export `ComboboxRehydrateValue` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 react-use@17.6.1 ``` - `vendor/apps/compositions/src/examples/combobox-rehydrate-value.tsx` ### With Custom Item `combobox-with-custom-item` · Named export `ComboboxWithCustomItem` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-custom-item.tsx` ### With Custom Filter `combobox-with-custom-filter` · Named export `ComboboxWithCustomFilter` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-custom-filter.tsx` ### With Custom Animation `combobox-with-custom-animation` · Named export `ComboboxWithCustomAnimation` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-custom-animation.tsx` ### Open From Popover `combobox-open-from-popover` · Named export `ComboboxOpenFromPopover` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-open-from-popover.tsx` ### With Createable `combobox-with-createable` · Named export `ComboboxWithCreateable` · original upstream example ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/combobox-with-createable.tsx` ## Native API and source references The source viewer retains original declarations, imports and inheritance. Ark UI event contracts, Chakra style props and recipe types stay in their native packages; this guide does not flatten or invent their defaults. Code comments remain original source, not translated prose. - `npm/@chakra-ui/react@3.37.0/dist/types/components/combobox/combobox.d.ts` - `npm/@chakra-ui/react@3.37.0/dist/types/components/combobox/index.d.ts` - `npm/@chakra-ui/react@3.37.0/dist/types/components/combobox/namespace.d.ts` ## State and installation checks Run strict types, the target production build and real interactions. Test labels/focus/keyboard, both themes, narrow layout, empty/loading/error states where supported and cleanup after unmount. Remote demo endpoints, uploads and downloads are constrained in the preview; configure your own services. Copying a command or reaching preview-ready does not prove installation or backend success. ## Provenance and license boundaries https://github.com/chakra-ui/chakra-ui/tree/2e7517745cff2fcde0b8012f136cf99611ff262a These are JGuang practical bilingual notes, not a full translation of upstream MDX. Original documentation and example bytes remain in vendor. Preserve repository MIT, compositions ISC metadata and separate dependency notices. The original metadata discrepancy and any missing full notices remain explicit review items; paid Chakra Pro is excluded. --- Index of all JGuang resources: https://jiguang132.com/llms.txt