Combobox

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

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.

"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 (
    <Combobox.Root
      collection={collection}
      onInputValueChange={(e) => filter(e.inputValue)}
      width="320px"
    >
      <Combobox.Label>Select framework</Combobox.Label>
      <Combobox.Control>
        <Combobox.Input placeholder="Type to search" />
        <Combobox.IndicatorGroup>
          <Combobox.ClearTrigger />
          <Combobox.Trigger />
        </Combobox.IndicatorGroup>
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner>
          <Combobox.Content>
            <Combobox.Empty>No items found</Combobox.Empty>
            {collection.items.map((item) => (
              <Combobox.Item item={item} key={item.value}>
                {item.label}
                <Combobox.ItemIndicator />
              </Combobox.Item>
            ))}
          </Combobox.Content>
        </Combobox.Positioner>
      </Portal>
    </Combobox.Root>
  )
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0

vendor/apps/compositions/src/examples/combobox-with-custom-animation.tsx

combobox-open-from-popover · Named export ComboboxOpenFromPopover · original upstream example

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

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.

Combobox

Combobox

Included icon notices

Setup and structure

State and examples

Async search and rehydration

Acceptance and provenance

Installation and initialization

Complete native usage example

All examples and reproduction requirements

Basic

With Sizes

With Variants

With Multiple

With Async Content

With Highlight

Open On Click

With Custom Object

Min Character

With Field

With Form Submit

With Hook Form

With Disabled

With Disabled Item

With Input Group

With Invalid

Controlled

With Store

Open Controlled

With Limit

Virtualized

With Links

Rehydrate Value

With Custom Item

With Custom Filter

With Custom Animation

Open From Popover

With Createable

Native API and source references

State and installation checks

Provenance and license boundaries