Combobox

A combobox is a form element that allows the user to select one or more options from a set of choices.

Third Party Library

This component uses at least one third party library under the hood. Refer to the library's documentation below for more information on the API.

HeadlessUI Combobox Documentation

Import

import { Combobox } from "@aeonkit/react";

Usage

Note about functionality

This component requires programming logic for the filtering, selection, and removal of items.

Create an array of anything you want to use as options. For these examples, we’ll use an array of objects with label and value keys.

const cities = [
  {
    label: "Houston, TX",
    value: "houston",
  },
  {
    label: "Austin, TX",
    value: "austin",
  },
  {
    label: "Dallas, TX",
    value: "dallas",
  },
  {
    label: "San Antonio, TX",
    value: "san-antonio",
  },
  {
    label: "Fort Worth, TX",
    value: "fort-worth",
  },
  {
    label: "Los Angeles, CA",
    value: "los-angeles",
  },
  {
    label: "San Diego, CA",
    value: "san-diego",
  },
  {
    label: "San Francisco, CA",
    value: "san-francisco",
  },
  {
    label: "San Jose, CA",
    value: "san-jose",
  },
  {
    label: "Sacramento, CA",
    value: "sacramento",
  },
]

Single

Single combobox allows only one item to be selected at a time.

Preview

Code

<Combobox
      value={selectedCity}
      onChange={setSelectedCity}
      onClose={() => setQuery("")}>
      <Combobox.Input
        displayValue={(city: (typeof cities)[number]) => city?.label}
        onChange={(event) => setQuery(event.target.value)}
      />
      <Combobox.Options>
        {filteredCities.map((city) => (
          <Combobox.Option key={city.value} value={city}>
            {city.label}
          </Combobox.Option>
        ))}
      </Combobox.Options>
    </Combobox>

Multiple

Multiple combobox allows multiple items to be selected at a time. Use the multiple prop to enable this feature.

Preview

Houston, TX Los Angeles, CA

Code

<Combobox
  multiple
  value={selectedCities}
  onChange={setSelectedCities}
  onClose={() => setQuery("")}
>
  <Combobox.Input
    onChange={(event) => setQuery(event.target.value)}
    placeholder="California and Texas Cities"
  />
  <Combobox.Options>
    {filteredCities.map((city) => (
      <Combobox.Option key={city.value} value={city}>
        {city.label}
      </Combobox.Option>
    ))}
  </Combobox.Options>
  {selectedCities.length > 0 && (
    <div className="my-4 flex flex-col sm:flex-row gap-2">
      {selectedCities.map((city) => (
        <Badge key={city.value} color="primary" className="flex flex-row gap-2">
          {city.label}{" "}
          <LuX
            onClick={() => removeCity(city)}
            size={14}
            className={cn("cursor-pointer bg-transparent hover:bg-transparent")}
          />
        </Badge>
      ))}
    </div>
  )}
</Combobox>

Styling states

You can style the selected and focused states by using data attributes. For example:

<Combobox.Option
  value={city}
  className="group flex gap-2 bg-white data-[focus]:bg-blue-100"
>
  <LuCheck className="invisible size-5 group-data-[selected]:visible" />
  {city.label}
</Combobox.Option>

Read more about styling states. Note: You can not style via render props at this time.

Props

Combobox

API Interface: ComboboxProps

Combobox.Option

API Interface: ComboboxOptionProps

Combobox.Options

API Interface: ComboboxOptionsProps

Combobox.Input

API Interface: ComboboxInputProps