Combobox

Searchable dropdown for selecting from a filterable list of options.

Building blocks: Combobox, ComboboxInput, ComboboxContent, ComboboxList, ComboboxItem, plus chips for multi-select (ComboboxChips, ComboboxChip, ComboboxChipsInput, useComboboxAnchor). For a closed button that opens a searchable list, use ComboboxTriggerButton + ComboboxSearch inside the popup. Popup lists use ScrollArea with edge hints.

Filtering requires this structure (Base UI):

Pass items={...} on Combobox (the filterable collection).
Put ComboboxEmpty as a sibling of ComboboxList, not inside it.
Give ComboboxList a single function child (item) => <ComboboxItem value={item}>….

Static <ComboboxItem> children without items never filter — you’ll see the full list and “No results” together. That was the old Radix-style demo shape.

autoHighlight (optional) highlights the first match while typing. Prefer Form.Combobox in product forms — see Form.

Basic

<HStack justify="center">
  <Combobox items={[...FRAMEWORKS]} autoHighlight>
    <ComboboxInput placeholder="Select a framework..." className="w-56" />
    <ComboboxContent>
      <ComboboxEmpty>No framework found.</ComboboxEmpty>
      <ComboboxList>
        {(name: string) => (
          <ComboboxItem key={name} value={name}>
            {name}
          </ComboboxItem>
        )}
      </ComboboxList>
    </ComboboxContent>
  </Combobox>
</HStack>

Multiple (chips)

Base UI / shadcn pattern: multiple + ComboboxChips + ComboboxValue (render chips) + list function child. Type to filter, pick items, remove with chip ×.

apparel

summer

import { useState } from 'react'
import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
  HStack,
  useComboboxAnchor,
} from '@vesyl/ui-next'

const TAGS = ['apparel', 'summer', 'clearance', 'fragile', 'gift', 'priority', 'wholesale']

/**
 * Multi-select with chips — Base UI / shadcn pattern:
 * multiple + ComboboxChips + ComboboxValue + list function child.
 */
export default function ComboboxMultiple() {
  const [value, setValue] = useState<string[]>(['apparel', 'summer'])
  const anchor = useComboboxAnchor()

  return (
    <HStack justify="center" className="w-full max-w-md">
      <Combobox
        multiple
        items={TAGS}
        value={value}
        onValueChange={(next) => setValue((next as string[]) ?? [])}
        itemToStringLabel={(v) => v}
      >
        <ComboboxChips ref={anchor} className="w-full">
          <ComboboxValue>
            {(selected: string[]) => (
              <>
                {selected.map((t) => (
                  <ComboboxChip key={t}>{t}</ComboboxChip>
                ))}
                <ComboboxChipsInput placeholder={selected.length === 0 ? 'Add tags…' : ''} />
              </>
            )}
          </ComboboxValue>
        </ComboboxChips>
        <ComboboxContent anchor={anchor}>
          <ComboboxEmpty>No tags found.</ComboboxEmpty>
          <ComboboxList>
            {(tag: string) => (
              <ComboboxItem key={tag} value={tag}>
                {tag}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </HStack>
  )
}

With groups

<HStack justify="center">
  <Combobox
    items={GROUPS}
    itemToStringLabel={(city: City) => city.label}
    autoHighlight
  >
    <ComboboxInput placeholder="Select a location..." className="w-56" />
    <ComboboxContent>
      <ComboboxEmpty>No location found.</ComboboxEmpty>
      <ComboboxList>
        {(group: CityGroup) => (
          <ComboboxGroup key={group.value} items={group.items}>
            <ComboboxLabel>{group.value}</ComboboxLabel>
            <ComboboxCollection>
              {(city: City) => (
                <ComboboxItem key={city.value} value={city}>
                  {city.label}
                </ComboboxItem>
              )}
            </ComboboxCollection>
          </ComboboxGroup>
        )}
      </ComboboxList>
    </ComboboxContent>
  </Combobox>
</HStack>

Picker (button trigger)

Closed control, search inside the popup — the pattern for long grouped catalogs. size="sm" on ComboboxContent densifies labels and rows; ComboboxSearch is the padded in-popup field.

import { useState } from 'react'
import {
  Combobox,
  ComboboxCollection,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
  ComboboxSearch,
  ComboboxTriggerButton,
  HStack,
} from '@vesyl/ui-next'

type Field = { id: string; label: string }

type FieldGroup = {
  value: string
  items: Field[]
}

const GROUPS: FieldGroup[] = [
  {
    value: 'Order',
    items: [
      { id: 'status', label: 'Order status' },
      { id: 'tags', label: 'Order tags' },
      { id: 'total', label: 'Order total (USD)' },
      { id: 'weight', label: 'Order weight' },
      { id: 'customer', label: 'Customer name' },
      { id: 'phone', label: 'Has phone number' },
    ],
  },
  {
    value: 'Destination',
    items: [
      { id: 'country', label: 'Country' },
      { id: 'state', label: 'State' },
      { id: 'city', label: 'City' },
      { id: 'postal', label: 'Postal code' },
      { id: 'po-box', label: 'Address is PO box' },
    ],
  },
  {
    value: 'Products',
    items: [
      { id: 'sku', label: 'Product SKU' },
      { id: 'name', label: 'Product name' },
      { id: 'qty', label: 'Product quantity' },
      { id: 'line-weight', label: 'Line item weight' },
    ],
  },
  {
    value: 'Parcel & shipping',
    items: [
      { id: 'parcel-weight', label: 'Parcel weight' },
      { id: 'method', label: 'Shipping method' },
      { id: 'rate', label: 'Has selected rate' },
      { id: 'zone', label: 'USPS zone' },
    ],
  },
]

export default function ComboboxPicker() {
  const [selected, setSelected] = useState<Field | null>(
    GROUPS[1]?.items.find((item) => item.id === 'country') ?? null,
  )

  return (
    <HStack justify="center">
      <Combobox
        items={GROUPS}
        value={selected}
        onValueChange={setSelected}
        itemToStringLabel={(item: Field) => item.label}
        isItemEqualToValue={(a: Field, b: Field) => a.id === b.id}
        autoHighlight
      >
        <ComboboxTriggerButton className="w-64">
          {selected?.label ?? 'Select a field'}
        </ComboboxTriggerButton>
        <ComboboxContent align="start" size="sm" className="w-72">
          <ComboboxSearch placeholder="Search fields…" />
          <ComboboxEmpty>No fields match</ComboboxEmpty>
          <ComboboxList>
            {(group: FieldGroup) => (
              <ComboboxGroup key={group.value} items={group.items}>
                <ComboboxLabel>{group.value}</ComboboxLabel>
                <ComboboxCollection>
                  {(item: Field) => (
                    <ComboboxItem key={item.id} value={item} indicator={false}>
                      {item.label}
                    </ComboboxItem>
                  )}
                </ComboboxCollection>
              </ComboboxGroup>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </HStack>
  )
}

With clear button

<HStack justify="center">
  <Combobox items={[...STATUSES]} autoHighlight>
    <ComboboxInput placeholder="Select a status..." showClear className="w-56" />
    <ComboboxContent>
      {/* Empty must be a sibling of List, not a child — List’s only child should be the render fn */}
      <ComboboxEmpty>No status found.</ComboboxEmpty>
      <ComboboxList>
        {(status: string) => (
          <ComboboxItem key={status} value={status}>
            {status}
          </ComboboxItem>
        )}
      </ComboboxList>
    </ComboboxContent>
  </Combobox>
</HStack>

Disabled

<HStack justify="center">
  <Combobox items={[...FRAMEWORKS]} disabled>
    <ComboboxInput placeholder="Disabled…" className="w-56" />
    <ComboboxContent>
      <ComboboxEmpty>No framework found.</ComboboxEmpty>
      <ComboboxList>
        {(name: string) => (
          <ComboboxItem key={name} value={name}>
            {name}
          </ComboboxItem>
        )}
      </ComboboxList>
    </ComboboxContent>
  </Combobox>
</HStack>

With disabled items

<HStack justify="center">
  <Combobox
    items={PLANS.map((p) => p.value)}
    autoHighlight
  >
    <ComboboxInput placeholder="Select a plan..." className="w-64" />
    <ComboboxContent>
      <ComboboxEmpty>No plan found.</ComboboxEmpty>
      <ComboboxList>
        {(name: string) => {
          const plan = PLANS.find((p) => p.value === name)!
          return (
            <ComboboxItem key={name} value={name} disabled={plan.disabled}>
              {name}
            </ComboboxItem>
          )
        }}
      </ComboboxList>
    </ComboboxContent>
  </Combobox>
</HStack>

Form.Combobox

RHF wrapper around the same composition. Field values stay string / string[]. With creatable, a synthetic list item is appended when the query has no exact match (Base UI creatable pattern) — selecting it commits the new string.

import { Form, Stack } from '@vesyl/ui-next'

const FRAMEWORKS = [
  { value: 'react', label: 'React' },
  { value: 'vue', label: 'Vue' },
  { value: 'svelte', label: 'Svelte' },
  { value: 'solid', label: 'Solid' },
]

const TAGS = ['apparel', 'summer', 'clearance', 'fragile', 'gift', 'priority']

/**
 * Form.Combobox — single (searchable select) and multiple+creatable (tags).
 */
export default function FormComboboxDemo() {
  return (
    <Form
      defaultValues={{ framework: null as string | null, tags: ['apparel'] as string[] }}
      onSubmit={() => {}}
      className="w-full max-w-md"
    >
      <Stack gap={4}>
        <Form.Field name="framework" label="Framework">
          <Form.Combobox items={FRAMEWORKS} placeholder="Search frameworks…" className="w-full" />
        </Form.Field>
        <Form.Field
          name="tags"
          label="Tags"
          description="Type to filter or create a new tag."
        >
          <Form.Combobox
            multiple
            creatable
            items={TAGS}
            placeholder="Add tags…"
            emptyMessage="No matching tags"
          />
        </Form.Field>
        <Form.SubmitButton type="button">Save</Form.SubmitButton>
      </Stack>
    </Form>
  )
}

External search

For server-backed catalogs, control the query with inputValue and onInputValueChange, and set filterMode="external". External mode renders items as supplied instead of applying Base UI’s client filter a second time. loading shows loadingMessage (default Loading…) and temporarily suppresses a speculative Create row. Selecting, creating, or clearing sends an empty query through onInputValueChange; debounce or fetch from that callback as needed.

const [query, setQuery] = useState("");

<Form.Combobox
  multiple
  creatable
  items={results}
  inputValue={query}
  onInputValueChange={setQuery}
  filterMode="external"
  loading={fetching}
  loadingMessage="Searching tags…"
/>;

Selected chips are retained when an external result page is replaced, including the last known option label. Omit these props for the existing client-filtered, internally managed behavior.

Reference

ComboboxContent

Prop	Type	Default	Description
`size`	`"md" \| "sm"`	`"md"`	Popup list density for items and group labels
`align`	`"start" \| "center" \| "end"`	`"start"`	Alignment along the trigger edge

ComboboxTriggerButton

Button-styled trigger for the picker layout. Defaults to variant="secondary", size="sm", font-normal. Pass variant="ghost" to blend into a toolbar.

ComboboxSearch

Padded search field for inside the popup. Use with ComboboxTriggerButton. Do not put ComboboxInput in the popup by hand — this owns the inset.

ComboboxList

Prop	Type	Default	Description
`flush`	`boolean`	`true` outside a popup, `false` inside `ComboboxContent`	Drop the bottom gutter so an inline list can sit against a parent scroller or footer. Popup lists keep the highlight-radius gutter.

ComboboxItem / ComboboxLabel

size is inherited from ComboboxContent. indicator={false} selects with accent fill instead of a check column.