Combobox

Searchable input for filtering and choosing from a list.

Installation

npx shadcn@latest add @iconiq/b-combobox

File Structure

Usage

"use client";

import { useState } from "react";

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/b-combobox";

type RouteOption = {
  value: string;
  label: string;
  description: string;
};

const options: RouteOption[] = [
  {
    value: "scout",
    label: "Scout pass",
    description: "First scan before the sprint opens up",
  },
  {
    value: "transit",
    label: "Transit window",
    description: "Tighter route through the midfield line",
  },
  {
    value: "deep",
    label: "Deep field",
    description: "Longer view with less traffic around it",
  },
  {
    value: "late-run",
    label: "Late run",
    description: "Arrive second and attack the gap late",
  },
];

export function ComboboxPreview() {
  const [value, setValue] = useState<RouteOption | null>(options[1]);

  return (
    <div className="w-full max-w-sm">
      <Combobox
        itemToStringLabel={(item) => item.label}
        itemToStringValue={(item) => item.value}
        items={options}
        onValueChange={setValue}
        value={value}
      >
        <ComboboxInput label="Pick a route" placeholder="Search routes..." />
        <ComboboxContent>
          <ComboboxList>
            {(option: RouteOption, index: number) => (
              <ComboboxItem
                description={option.description}
                index={index}
                key={option.value}
                value={option}
              >
                {option.label}
              </ComboboxItem>
            )}
          </ComboboxList>
          <ComboboxEmpty>No route matches that query.</ComboboxEmpty>
        </ComboboxContent>
      </Combobox>
    </div>
  );
}

Props

Props
Description

Combobox

items

Optional item collection used by Base UI for filtering and render-function lists.

Type readonly Item[]

value

Controlled selected value. Use an array when multiple is true.

Type Item | Item[] | null

defaultValue

Initial selected value for uncontrolled usage.

Type Item | Item[] | null

onValueChange

Called when an item is selected, a chip is removed, or the clear action resets the selection.

Type (value, eventDetails) => void

multiple

Allows selecting multiple items. Pair with ComboboxChips, ComboboxChip, and ComboboxChipsInput.

Type boolean·Default false

itemToStringLabel

Maps object values to the label shown in the input and used for text filtering.

Type (item: Item) => string

itemToStringValue

Maps object values to the hidden form value.

Type (item: Item) => string

isItemEqualToValue

Custom equality check for object values. Defaults to Object.is.

Type (item, value) => boolean

inputValue

Controlled search text. Leave uncontrolled for Base UI to manage query state.

Type string

onInputValueChange

Called when the typed query changes.

Type (inputValue, eventDetails) => void

autoHighlight

Automatically highlights the first matching item while filtering.

Type boolean·Default false

open

Controlled popup state. Pair with onOpenChange.

Type boolean

onOpenChange

Called when the popup opens or closes.

Type (open, eventDetails) => void

openOnInputClick

When true, clicking the input shell opens the popup. Otherwise only focus is moved.

Type boolean·Default false

onItemHighlighted

Called when the highlighted item changes from keyboard or pointer navigation.

Type (value, eventDetails) => void

ComboboxInput

label

Optional label rendered above the input shell with an associated htmlFor.

Type ReactNode

placeholder

Shown when no item is selected and the input is empty.

Type string

showClear

Controls whether ComboboxClear is rendered in the input.

Type boolean·Default true

showTrigger

Controls whether the rotating trigger icon is rendered in the input.

Type boolean·Default true

size

Controls the input shell height.

Type "sm" | "default"·Default "default"

className

Merged onto the wrapper when label is set, otherwise onto the input shell.

Type string

disabled

Disables the input, clear button, and trigger while applying reduced-opacity presentation.

Type boolean·Default false

aria-invalid

When true, applies destructive border and ring styling to the input shell.

Type boolean

ComboboxClear

disabled

Prevents clearing while disabled.

Type boolean·Default false

className

Merged onto the clear button.

Type string

ComboboxTrigger

disabled

Prevents toggling while disabled.

Type boolean·Default false

className

Merged onto the trigger button.

Type string

ComboboxStatus

children

Status message content. Keep the root mounted and update children instead of conditionally rendering the component.

Type ReactNode

className

Merged onto the status container.

Type string

ComboboxContent

side

Preferred side for the popup.

Type "top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"·Default "bottom"

align

Popup alignment relative to the input anchor.

Type "start" | "center" | "end"·Default "start"

sideOffset

Gap between the input shell and dropdown.

Type number·Default 4

className

Merged onto the animated popup panel.

Type string

ComboboxList

children

Render explicit children or a render function when using the root items prop.

Type ReactNode | ((item, index) => ReactNode)

className

Merged with the default list spacing and scroll classes.

Type string

ComboboxItem

value

Stable value used by Base UI for selection.

Type Item

children

Primary item label content.

Type ReactNode

description

Optional secondary line rendered below the item label, matching the prior option description UI.

Type ReactNode

className

Merged with the default row layout and motion classes.

Type string

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react, motion, lucide-react.

This page documents the Base UI install only, because Radix UI does not ship a dedicated combobox primitive.

Install into components/ui/b-combobox.tsx so imports match the usage examples.

The generated registry file is /r/b-combobox.json.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

Selected: Transit window