Skip to content
WunderUI

Combobox

Free

A text field joined to a list of choices. Type to narrow the list, then pick one: the field only ever holds a value from the list.

npx wunderui-cli add combobox

Playground

Installation

bash
npx wunderui-cli add combobox

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Combobox,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxGroupLabel,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxPortal,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import type { ComboboxItemGroup, ComboboxProps } from "@/components/ui/combobox"

Then use it:

tsx
import { useState } from "react"
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"

const projects = ["Brand refresh", "Mobile app", "Onboarding revamp", "Pricing experiment", "Q4 roadmap"]

export function ProjectField() {
  const [project, setProject] = useState<string | null>(null)

  return (
    <Combobox items={projects} value={project} onValueChange={setProject}>
      <ComboboxInputGroup>
        <ComboboxInput aria-label="Project" placeholder="Search projects" />
        <ComboboxTrigger />
      </ComboboxInputGroup>
      <ComboboxPopup>
        <ComboboxEmpty>No projects match.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxPopup>
    </Combobox>
  )
}

Expected result: You see a field with the placeholder Search projects and a chevron. A click opens five projects, typing re keeps two, and Enter on one fills the field with its name.

When to use

Use Combobox for

  • Choosing one entry from a long list people can search, such as a country, a project or a person
  • Choosing several entries, such as the teams to filter a table by
  • Any field whose value must be one of the entries

Use something else for

  • Select for a short list where typing is not needed
  • Autocomplete for free text that only gets suggestions
  • Radio Group for two to four options that should all be visible

Content

An entry is a row you build: plain text, text under a group label, or a person with an avatar and a second line. Give the item an object as its value when it carries more than a label.

Selection

By default one entry is chosen and the list closes. With multiple, the list stays open and each chosen entry shows a check, but you show the chosen entries yourself, for example as a count.

Field

The chevron button opens and closes the whole list, which tells people the field is a list of choices. Leave it out when the list is long and people are expected to type.

States

Hover and focus are real states, so point at the field or press Tab. An invalid input turns the border and ring red with a line saying why, and a disabled field dims and ignores input.

Keyboard interactions

The input is a native text field, so the browser handles focus, typing and the caret. Focus stays in the input while the list is open, and the chevron button is not in the tab order.

TaborShiftTab
Moves focus into the field and out of it. Leaving closes the list. Text that was typed but not chosen is dropped, and the field shows the chosen entry again.
A–Z
Typing opens the list and keeps the entries that match.
ArrowDownorArrowUp
Opens the list if it is closed, then moves the highlight to the next or previous entry. With an entry chosen the list opens with it highlighted. At the end of the list focus goes back to the text with nothing highlighted.
Enter
Chooses the highlighted entry: the field shows its label and the list closes. With it toggles the entry and the list stays open.
Escape
Closes the list. Pressed again, it clears the choice.

Behavior and motion

What the field does with its value, the typed text, the list and motion.

A value from the list
The value is an entry of the items, or null while nothing is chosen. Typing alone never sets it, so the value changes only when an entry is chosen.
Opening
The list opens on a click in the field, on typing, on the chevron and on Arrow Down. The chevron button opens and closes it.
Filtering
An entry matches when it contains the typed text, ignoring case and accents. You can replace the rule or cap the list, and after a choice the list opens unfiltered.
Groups
Pass groups as items with a label and entries, and render a group and group label for each. The filter works across groups, and a group with no match disappears with its label.
Single and multiple
By default one entry is chosen and the list closes. With multiple the value is an array, the list stays open and every chosen entry shows a check, but the field does not list them.
Objects as items
Items can be objects. Give each item the object as its value, the root a function for the field text, and an equality check when the objects are not the same references.
Position and size
The list opens 4 px below the field, as wide as the field, and flips above when there is no room below. It scrolls when it is taller than the room left.
Invalid and disabled
Marking the input invalid turns the border and focus ring red, so say why in a line under the field. Disabling the root dims the field to 40 % and it ignores pointer and keyboard.
Previews in these docs
The list normally floats over the page, but the previews here draw it inside the card. Point at a card or focus it, and the field behaves like the real one.
Motion
The list appears and disappears at once. Nothing else on the field moves, and the border and focus ring change colour quickly.
Reduced motion
There is no movement to remove, so reduced motion changes nothing. The colour change is a short fade and stays.

Anatomy

The parts of a combobox, numbered in the figure. The figure shows a grouped list with a chosen entry, and the empty line and the portal are listed below.

  • The root. It holds the chosen value, the typed text, the items and the filter, and the value is an item or null, or an array with multiple.

  • data-slot="combobox-input-group"Optional

    The bordered frame around the input and the chevron, 36 px high with an 8 px corner. It draws the border and focus ring, dims when disabled and turns red when the input is invalid.

  • data-slot="combobox-input"

    The text input: typing filters the list, arrow keys move through it, Enter chooses and Escape closes. Give it a visible label or an aria-label.

  • data-slot="combobox-trigger"Optional

    The chevron button that opens and closes the whole list. It is named Show options and is not in the tab order, because the keyboard opens the list from the input.

  • data-slot="combobox-popup"

    The list panel. It brings its own portal and positioner, matches the width of the field and scrolls when it runs out of room.

  • data-slot="combobox-list"

    Renders the entries. Pass a render function as the child, so the filtered list, not the full one, is mapped, and with groups it receives one group at a time.

  • data-slot="combobox-group"Optional

    Holds the entries of one group under a group label. A group without a match disappears with its label.

  • data-slot="combobox-group-label"Optional

    The heading of a group, in 12 px medium muted text. It is not an entry, so arrow keys skip it.

  • data-slot="combobox-item"

    One entry, 32 px high for a single line, whose value is what the field holds when chosen. A row can hold an icon, or an avatar and a second line, and the highlighted row takes the page fill.

  • Optional

    A 16 px check at the right of the chosen entry. With multiple, every chosen entry shows one.

  • data-slot="combobox-empty"Optional

    A centred line shown in place of the list when nothing matches. It is hidden while it has no content.

  • Optional

    Moves the list to the end of the document. The popup already renders it, so you only need it for a custom container.

Best practices

  • Do

    Give the input a visible label that points at it. The placeholder is a hint such as Search projects, not the name of the field.

  • Do

    Always include an empty-state line with a sentence such as No projects match, so a list without matches never looks broken.

  • Do

    Keep the state as a value or null. It is null while nothing is chosen and after the choice is cleared.

  • Do

    With multiple, show the chosen entries next to the field, as a count or a list. The field only shows what people type.

  • Do

    Group a long list by what people already know, such as an area or a team, and pass the groups as the items.

  • Don’t

    Don't use it for free text. Text that is not an entry is dropped when the field loses focus, so use an Autocomplete when any value is valid.

  • Don’t

    Don't use it for a short list people can see at a glance. A Select is quicker when there are about a dozen options or fewer.

  • Don’t

    Don't turn on multiple and then hide the choices. People cannot tell what is selected from a closed field with a placeholder.

API reference

Combobox wraps the Base UI combobox and passes its props on. The root takes the items and the value, every part also takes className, style and render, and the input takes the props of a native input.

The root. It holds the chosen value, the typed text, the items and the filter, and the value is an item or null, or an array with multiple.

PropTypeDefaultDescription
itemsreadonly Value[] | readonly ComboboxItemGroup<Value>[] | ComboboxItemCollection<Item, Value>—The entries: a flat array, an array of groups () or a collection from . A flat array or groups give its type.
valueComboboxValueType<Value, Multiple> | null—The chosen entry, or while nothing is chosen. With it is an array. It is a controlled value: update it in .
defaultValueComboboxValueType<Value, Multiple> | null—The entry that is chosen when you do not control the value.
onValueChange(value, eventDetails) => void—Called with the new choice: the entry, or when the choice is cleared. With it is the whole array.
multipleMultiplefalseLets people choose several entries. The value becomes an array, the list stays open while they choose, and each chosen entry shows a check.
inputValueComponentProps<"input">["value"]—The text in the field, when you control it. Pair it with .
defaultInputValueComponentProps<"input">["defaultValue"]—The text the field starts with when you do not control it.
onInputValueChange(inputValue, eventDetails) => void—Called with the new text each time the person types or the field changes to show a choice.
filternull | (item, query, itemToString?) => boolean—Replaces the matching rule. It receives an entry, the typed text and the function that turns an entry into text, and returns whether the entry stays in the list. switches filtering off.
itemToStringLabel(itemValue) => string—Turns an object entry into the text of the field and the text the filter matches against. Needed when the entries are objects.
isItemEqualToValue(itemValue, value) => boolean—Decides whether an entry is the chosen value. Needed when entries are objects that are not the same references as the value.
autoHighlightbooleanfalseHighlights the first matching entry while people type, so Enter chooses it.
limitnumber-1The most entries the list shows. , the default, shows every match.
openOnInputClickbooleantrueOpens the list when the field is clicked. On by default.
openboolean—Whether the list is open, when you control it. Pair it with .
defaultOpenbooleanfalseWhether the list starts open when you do not control it.
onOpenChange(open, eventDetails) => void—Called when the list opens or closes, with the reason, such as typing, a key press, an outside press or choosing an entry.
disabledbooleanfalseDisables the field: it dims to 40 % and ignores the pointer and the keyboard.
readOnlybooleanfalseKeeps the value but stops people from choosing another entry.
requiredbooleanfalseMarks the field as required for the form it belongs to.
namestring—The name the chosen value is submitted under in a form.
actionsRefRefObject<ComboboxRoot.Actions | null>—A ref to imperative actions. - : Manually unmounts the combobox. Call this after any externally controlled closing animation finishes.
autoCompletestring—Provides a hint to the browser for autofill.
childrenReactNode—
filteredItemsreadonly Item[] | readonly Group<Item>[]—Filtered items to display in the list. When provided, the list uses these items instead of filtering the prop internally. When is also provided, this array must preserve its flat or grouped structure. With a …
formstring—Identifies the form that owns the internal input. Useful when the combobox is rendered outside the form.
gridbooleanfalseWhether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
highlightItemOnHoverbooleantrueWhether moving the pointer over items should highlight them. Disabling this prop allows CSS to be differentiated from the () state.
idstring—The id of the component.
inlinebooleanfalseWhether the list is rendered inline without using the component's own popup. Specify unconditionally in conjunction with this prop so the list is considered visible: In a > …
inputRefRef<HTMLInputElement>—A ref to the hidden input element.
itemToStringValue(itemValue) => string—When the item values are objects (), this function converts the object value to a string representation for form submission. If the shape of the object is , the value will be used automatic…
localeIntl.LocalesArgument—The locale to use for string comparison. Defaults to the user's runtime locale.
loopFocusbooleantrueWhether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by p…
modalbooleanfalseDetermines if the popup enters a modal state when open. - : user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. - : user interaction with the rest…
onItemHighlighted(highlightedValue, eventDetails) => void—Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or if no item is highlighted) and event details with a property describing why the highlight changed. The can b…
onOpenChangeComplete(open) => void—Event handler called after any animations complete when the popup is opened or closed.
virtualizedbooleanfalseWhether the items are being externally virtualized.

The bordered frame around the input and the chevron, 36 px high with an 8 px corner. It draws the border and focus ring, dims when disabled and turns red when the input is invalid.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the frame, for example for a fixed width or for the large height.

The text input: typing filters the list, arrow keys move through it, Enter chooses and Escape closes. Give it a visible label or an aria-label.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the input inside the frame.
disabledbooleanfalseDisables this input only. Prefer on the root, which also dims the frame.

The chevron button that opens and closes the whole list. It is named Show options and is not in the tab order, because the keyboard opens the list from the input.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the chevron button.
disabledbooleanfalseDisables the chevron button only.
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).

The list panel. It brings its own portal and positioner, matches the width of the field and scrolls when it runs out of room.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the list panel, for example to make it wider than the field.
finalFocusboolean | RefObject<HTMLElement | null> | (closeType) => unknown—Where focus goes when the list closes. It stays in the input by default.
initialFocusboolean | RefObject<HTMLElement | null> | (openType) => unknown—Where focus goes when the list opens. It stays in the input by default, so people can keep typing.

Renders the entries. Pass a render function as the child, so the filtered list, not the full one, is mapped, and with groups it receives one group at a time.

PropTypeDefaultDescription
childrenReactNode | (item, index) => ReactNode—A render function that receives the entries that match, or the groups that have a match, and returns the rows.
classNamestring | (state) => string | undefined—Extra classes for the list element inside the panel.

Holds the entries of one group under a group label. A group without a match disappears with its label.

PropTypeDefaultDescription
itemsreadonly any[]—The entries of this group. Pass the group's own so the list can tell which entries belong to it.
classNamestring | (state) => string | undefined—Extra classes for the group wrapper.

The heading of a group, in 12 px medium muted text. It is not an entry, so arrow keys skip it.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the group heading.

One entry, 32 px high for a single line, whose value is what the field holds when chosen. A row can hold an icon, or an avatar and a second line, and the highlighted row takes the page fill.

PropTypeDefaultDescription
valueanynullThe entry this row stands for, the same string or object as in . It is what the field holds when the row is chosen.
disabledbooleanfalseStops the row from being highlighted or chosen.
onClickBaseUIComponentProps<"div", ComboboxItemState>["onClick"]—Called when the row is clicked or chosen with Enter.
classNamestring | (state) => string | undefined—Extra classes for the row, for example for a row with an avatar.
childrenReactNode—
indexnumber—The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.
nativeButtonbooleanfalseWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is a native button.

A centred line shown in place of the list when nothing matches. It is hidden while it has no content.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the line shown when nothing matches.

Moves the list to the end of the document. The popup already renders it, so you only need it for a custom container.

PropTypeDefaultDescription
containerHTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null—The element the list is moved into. The end of the document by default.
keepMountedbooleanfalseKeeps the list in the DOM while it is closed.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("combobox")
Installnpx wunderui-cli add combobox

The full library index for assistants is at /llms.txt.