Combobox React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Combobox is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Combobox from @/components/ui/combobox.

import { useState } from "react"
import { MapPin } from "lucide-react"
import { Combobox, type ComboboxItems } from "@/components/ui/combobox"

async function searchCities(query: string, { signal }: { signal: AbortSignal }): Promise<ComboboxItems> {
  const response = await fetch(`/api/cities?q=${encodeURIComponent(query)}`, { signal })
  const cities: { id: string; name: string; state: string }[] = await response.json()
  return cities.map((city) => ({ value: city.id, label: city.name, description: city.state }))
}

export function CityField() {
  const [city, setCity] = useState("")
  return (
    <Combobox
      label="City"
      placeholder="Search for a city"
      leftIcon={<MapPin />}
      loadOptions={searchCities}
      minQueryLength={1}
      value={city}
      onValueChange={setCity}
      emptyText="No cities found"
      errorText="Could not load cities"
      sheetTitle="Search cities"
      name="city"
    />
  )
}

Props

• labeldefault ""
  ReactNode

  The label above the field; renders the field anatomy and names the list and the phone sheet.

• descriptiondefault ""
  ReactNode

  Helper text under the field, linked with aria-describedby.

• errordefault ""
  ReactNode

  Replaces the description with an animated error and marks the field invalid.

• requireddefault false
  boolean

  A red * after the label and required on the input.

• invaliddefault false
  boolean

  The invalid look and aria-invalid without a message.

• disableddefault false
  boolean

  Dims the field and blocks typing and opening.

• readOnlydefault false
  boolean

  The text stays visible and focusable; nothing opens and nothing can be typed.

• optionsdefault "[]"
  ComboboxItems ((ComboboxOption | { label?: ReactNode; items: ComboboxOption[] })[])

  Options and groups, filtered locally as you type. An option is { value, label, description?, icon?, badge?, disabled?, keywords?, textValue? }. With loadOptions they show while the query is shorter than minQueryLength.

• loadOptions
  (query: string, context: { signal: AbortSignal }) => Promise<ComboboxItems>

  Server search for the debounced query. The results replace the list, the previous ones stay while loading, a newer query aborts the older request, and the last 20 answers are cached.

• debouncedefault 250
  number

  Milliseconds of quiet before loadOptions runs.

• minQueryLengthdefault 0
  number

  loadOptions waits for this many characters.

• filterdefault true
  boolean, or (option: ComboboxOption, query: string) => score (number, null hides)

  true filters with text-match on the label and keywords; false means the options are already filtered; a function scores each option (null hides it).

• fuzzydefault false
  boolean

  Letters in order may have gaps ("sfco" finds San Francisco).

• value
  string

  The chosen option's value (or the free text with allowCustomValue), controlled. A value that is not in the current results shows the cached option text, else the value.

• defaultValuedefault ""
  string

  The starting value while uncontrolled. A form reset returns to it.

• onValueChange
  (value: string) => void

  Called with the new value; "" when it clears.

• inputValue
  string

  The text in the field, controlled.

• defaultInputValuedefault ""
  string

  The starting text while uncontrolled; it filters the list like typed text.

• onChange
  (event: ChangeEvent<HTMLInputElement>) => void

  The native change event of every keystroke, untouched (react-hook-form's register works).

• onInputValueChange
  (text: string) => void

  Called on every keystroke and when the text snaps to an option.

• allowCustomValuedefault false
  boolean

  The typed text is a valid value (a street, a free label): it becomes the value on blur or Enter. Otherwise the text snaps back to the chosen option.

• creatabledefault false
  boolean

  A create row when nothing matches exactly (first and highlighted when there are no results).

• onCreate
  (query: string) => (string | void | Promise<string | void>)

  Runs for the create row; a returned value (or a promise of one) is selected, and a promise shows a spinner on the row. Without it the typed text becomes the value.

• createLabeldefault "(q) => `Create "${q}"`"
  (query: string) => ReactNode

  The create row's text.

• placeholderdefault ""
  string

  Shown while the field is empty, also in the phone sheet's search box.

• emptyTextdefault "No results"
  string

  Shown when the query matches nothing.

• loadingTextdefault "Loading…"
  string

  The first load's status row and the spinner's accessible name.

• errorTextdefault "Could not load results"
  string

  Shown when loadOptions fails, above a retry button.

• retryLabeldefault "Try again"
  string

  The retry button under errorText.

• clearLabeldefault "Clear"
  string

  The accessible name of the x button.

• toggleLabeldefault "Show suggestions"
  string

  The accessible name of the chevron button.

• highlightMatchesdefault true
  boolean

  The matched letters of each option in bold.

• openOnFocusdefault false
  boolean

  Opens with every option (or the recent picks you pass) as soon as the field gets focus.

• autoHighlightdefault true
  boolean

  The first match is highlighted, so Enter picks it. Turn it off for free text, where Enter should keep what you typed.

• clearabledefault true
  boolean

  An x while there is text or a value; Escape on a closed list clears too.

• leftIcon
  ReactNode

  An icon before the text, like a MapPin. Unsized svgs follow the size.

• sizedefault "md"
  "sm" | "md" | "lg"

  32 / 40 / 48px like every field; md grows to 44px on touch screens.

• variantdefault "soft"
  "soft" | "outline" | "underline" | "ghost"

  The box: a filled well, an outline, a bottom line, or nothing until hover.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape, scaled per size like the button (md is 8 / 10 / 12px); also the sheet's search box.

• defaultOpendefault false
  boolean

  Starts with the list (or the sheet) open. Pass open and onOpenChange to control it.

• open
  boolean

  Whether the list is open, controlled. It shows only when there is something to show, and never while disabled or readOnly.

• onOpenChange
  (open: boolean) => void

  Called when the list opens or closes.

• responsivedefault true
  boolean

  Below 768px the field opens a full-height search sheet instead of the popover.

• sheetTitledefault "Search"
  string

  The phone sheet's title for screen readers (its visible header is the search box); a string label wins.

• cancelLabeldefault "Cancel"
  string

  The text button next to the sheet's search box.

• sidedefault "bottom"
  "top" | "right" | "bottom" | "left"

  Where the list opens; it flips when there is no room.

• aligndefault "start"
  "start" | "center" | "end"

  How the list lines up with the field.

• maxHeightdefault 360
  number

  The list's height limit in px, capped by the room on screen.

• virtualThresholddefault 100
  number

  Above this many rows only the visible ones render.

• renderOption
  (option, state: { selected, highlighted, disabled, ranges }) => ReactNode

  Replaces a row's content; the row element, its aria and its classes stay.

• namedefault ""
  string

  Submits the value through a hidden input.

• id
  string

  The input's id; generated when left out.

• container
  HTMLElement | null

  Portal target for the list and the sheet (default document.body).

• fieldProps
  Partial<FieldProps>

  Anything else for the field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.

• classNames
  Partial<Record<"field" | "label" | "description" | "error" | "counter" | "root" | "box" | "input" | "leftIcon" | "spinner" | "clear" | "toggle" | "content" | "list" | "item" | "group" | "status" | "sheet" | "sheetSearch" | "cancel", string>>

  Extra classes for the inner parts. content is the popover, sheet the phone sheet.

• className
  string

  Extra classes for the outermost element: the Field when there is a label or message, else the combobox root.

• ref
  Ref<HTMLInputElement> (a useRef object or an (el) => void callback)

  The text input. Other props (onBlur, onKeyDown, autoFocus, aria-*, data-*) land on it too; onChange gets the native event.

FAQ

Used in

More React input components