Combobox

Multi-purpose combobox widget to allow selection from a dynamic set of options.

App.tsx


"use client";
 
import {
  Combobox,
  ComboboxContent,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
import { colors } from "./data";
 
export function App() {
  const [value, setValue] = useState<string>();
 
  return (
    <Combobox
      defaultItems={colors}
      isItemSelected={(item) => item === value}
      onItemSelect={setValue}
    >
      <ComboboxTrigger w="224">{value || "Set color"}</ComboboxTrigger>
      <ComboboxContent />
    </Combobox>
  );
}

#
Guide

#
Structure

Combobox works with lists of items provided via the defaultItems prop. The basic structure includes the main component provider, a trigger, and a content.

Combobox
ComboboxTrigger
ComboboxContent

Items can be an array of strings or it can be an array of objects.

The trigger can be provided a placeholder to display in case no values have been selected yet.


import {
  Combobox,
  ComboboxContent,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  return (
    <Combobox defaultItems={colors}>
      <ComboboxTrigger>Select color</ComboboxTrigger>
      <ComboboxContent />
    </Combobox>
  );
}

The ComboboxContent component further includes the input, a listbox, and a footer.

ComboboxInput
ComboboxListbox
ComboboxFooter

We’ll talk about them more in the following sections.

#
Listbox

By default content popover will render an input and the provided items. But we can customize how items are rendered using the ComboboxListbox component.

ComboboxListbox accepts a react node as well as a render prop where the first parameter is the item that needs to be rendered.


import {
  Combobox,
  ComboboxContent,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  return (
    <Combobox defaultItems={colors}>
      <ComboboxTrigger>Select color</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxListbox />
      </ComboboxContent>
    </Combobox>
  );
}

#
Single-select

We can render single-select items using ComboboxRadioItem.


"use client";
 
import {
  Combobox,
  ComboboxContent,
  ComboboxListbox,
  ComboboxRadioItem,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  return (
    <Combobox defaultItems={colors}>
      <ComboboxTrigger>Select color</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxListbox>
          {(item) => <ComboboxRadioItem item={item}>{item}</ComboboxRadioItem>}
        </ComboboxListbox>
      </ComboboxContent>
    </Combobox>
  );
}

#
Multi-select

We can render multi-select items using ComboboxCheckboxItem.


"use client";
 
import {
  Combobox,
  ComboboxCheckboxItem,
  ComboboxContent,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  return (
    <Combobox defaultItems={colors}>
      <ComboboxTrigger>Select colors</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxListbox>
          {(item) => (
            <ComboboxCheckboxItem item={item}>{item}</ComboboxCheckboxItem>
          )}
        </ComboboxListbox>
      </ComboboxContent>
    </Combobox>
  );
}

Notice that keyboard interactions inside the content popover do not work in the previous demos. This is because we need to render the ComboboxInput component that handles keyboard interaction and triggers filtering of visible items.


import {
  Combobox,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  return (
    <Combobox defaultItems={colors}>
      <ComboboxTrigger>Select color</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput placeholder="Search..." />
        <ComboboxListbox />
      </ComboboxContent>
    </Combobox>
  );
}

#
Filtering

Combobox automatically handles filtering when using the defaultItems prop using a built-in filter. We can override this filter using the defaultFilter prop or use the items prop to manually control the filtered list.

This example shows using defaultFilter to provide a custom filter function:


"use client";
 
import {
  Combobox,
  ComboboxContent,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  return (
    <Combobox
      defaultFilter={(color, inputValue) =>
        color.toLowerCase().startsWith(inputValue.toLowerCase())
      }
      defaultItems={colors}
    >
      <ComboboxTrigger>Select color</ComboboxTrigger>
      <ComboboxContent />
    </Combobox>
  );
}

#
Async loading

We can also manually control items in combination with the onInputValueChange prop to load items as the user types.

App.tsx


"use client";
 
import {
  Combobox,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
 
import { useQuery } from "./useQuery";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  const { data, isLoading, refetch } = useQuery((inputValue: string) =>
    inputValue
      ? colors.filter((color) =>
          color.toLowerCase().includes(inputValue.toLowerCase()),
        )
      : colors,
  );
 
  return (
    <Combobox
      items={data}
      onInputValueChange={(inputValue) => refetch(inputValue)}
    >
      <ComboboxTrigger w="224">Select colors</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput />
        <ComboboxListbox loading={isLoading} />
      </ComboboxContent>
    </Combobox>
  );
}

#
Selection

Pressing enter or clicking items will not do anything in previous demos. For that we need to add the isItemSelected and onItemSelect props to the main Combobox component.

isItemSelected: Return true if an item should be marked as selected where the item and the index are passed as parameters.
onItemSelect: Handler invoked when user selects an item with the item as the only parameter.

Developers are expected to manually track the selection on their side since items inside a combobox can represent values or actions.

#
Single-select


"use client";
 
import {
  Combobox,
  ComboboxContent,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  const [value, setValue] = useState<string>();
 
  return (
    <Combobox
      defaultItems={colors}
      isItemSelected={(item) => item === value}
      onItemSelect={(value) =>
        setValue((prev) => (prev !== value ? value : undefined))
      }
    >
      <ComboboxTrigger w="224">Select color</ComboboxTrigger>
      <ComboboxContent />
    </Combobox>
  );
}

#
Multi-select


"use client";
 
import {
  Combobox,
  ComboboxCheckboxItem,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  const [value, setValue] = useState<string[]>([]);
 
  return (
    <Combobox
      defaultItems={colors}
      isItemSelected={(item) => value.includes(item)}
      onItemSelect={(value) =>
        setValue((prev) =>
          prev.includes(value)
            ? prev.filter((v) => v !== value)
            : [...prev, value],
        )
      }
    >
      <ComboboxTrigger w="224">Select colors</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput />
        <ComboboxListbox>
          {(item) => (
            <ComboboxCheckboxItem item={item}>{item}</ComboboxCheckboxItem>
          )}
        </ComboboxListbox>
      </ComboboxContent>
    </Combobox>
  );
}

#
Empty

By default combobox will display a generic empty content message if no results are found matching your query. We can customize this empty message by setting the empty prop on ComboboxListbox.


"use client";
 
import {
  Combobox,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
const colors = ["Ocean", "Blue", "Purple", "Red", "Orange", "Yellow"];
 
export function App() {
  const [items, setItems] = useState(colors);
 
  return (
    <Combobox
      items={items}
      onInputValueChange={(inputValue) => {
        setItems(
          inputValue
            ? colors.filter((color) =>
                color.toLowerCase().startsWith(inputValue.toLowerCase()),
              )
            : colors,
        );
      }}
    >
      <ComboboxTrigger>Select color</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput />
        <ComboboxListbox empty="No colors matched." />
      </ComboboxContent>
    </Combobox>
  );
}

#
Documentation

#
Anatomy


import {
  Combobox,
  ComboboxCheckboxItem,
  ComboboxContent,
  ComboboxFooter,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxListbox,
  ComboboxRadioItem,
  ComboboxSeparator,
  ComboboxTrigger,
} from "@optiaxiom/react";
 
export default () => (
  <Combobox>
    <ComboboxTrigger />
 
    <ComboboxContent>
      <ComboboxInput />
 
      <ComboboxListbox>
        <ComboboxItem />
        <ComboboxCheckboxItem />
        <ComboboxRadioItem />
 
        <ComboboxGroup>
          <ComboboxLabel />
          <ComboboxItem />
          <ComboboxCheckboxItem />
          <ComboboxRadioItem />
        </ComboboxGroup>
 
        <ComboboxSeparator />
      </ComboboxListbox>
 
      <ComboboxFooter />
    </ComboboxContent>
  </Combobox>
);

#
Object data

Use the defaultItems or items prop to pass the collection of data to Combobox. Items can be an array of primitive types such as strings or it can be an array of objects.

In case item is an object you need to pass an additional itemToLabel prop for Combobox to work.

App.tsx


"use client";
 
import { Box } from "@optiaxiom/react";
import {
  Combobox,
  ComboboxCheckboxItem,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
import { type Color, colors } from "./data";
 
export function App() {
  const [value, setValue] = useState<Color[]>([]);
 
  return (
    <Combobox
      defaultItems={colors}
      isItemDisabled={(item) => Boolean(item.isDisabled)}
      isItemSelected={(item) => value.includes(item)}
      itemToLabel={(item) => (item ? item.label : "")}
      onItemSelect={(value) =>
        setValue((prev) =>
          prev.includes(value)
            ? prev.filter((v) => v !== value)
            : [...prev, value],
        )
      }
    >
      <ComboboxTrigger w="224">Select colors</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput />
        <ComboboxListbox>
          {(item) => (
            <ComboboxCheckboxItem
              icon={
                <Box
                  rounded="sm"
                  style={{ aspectRatio: 1, backgroundColor: item.color }}
                />
              }
              item={item}
            >
              {item.label}
            </ComboboxCheckboxItem>
          )}
        </ComboboxListbox>
      </ComboboxContent>
    </Combobox>
  );
}

#
Disabled

Use the optional isItemDisabled prop to configure which items should be disabled. The callback is passed the item and the index number as arguments and expects a boolean result.

App.tsx


"use client";
 
import { Box } from "@optiaxiom/react";
import {
  Combobox,
  ComboboxCheckboxItem,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
import { type Color, colors } from "./data";
 
export function App() {
  const [value, setValue] = useState<Color[]>([]);
 
  return (
    <Combobox
      defaultItems={colors}
      isItemDisabled={(item) => Boolean(item.isDisabled)}
      isItemSelected={(item) => value.includes(item)}
      itemToLabel={(item) => (item ? item.label : "")}
      onItemSelect={(value) =>
        setValue((prev) =>
          prev.includes(value)
            ? prev.filter((v) => v !== value)
            : [...prev, value],
        )
      }
    >
      <ComboboxTrigger w="224">Select colors</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput />
        <ComboboxListbox>
          {(item) => (
            <ComboboxCheckboxItem
              icon={
                <Box
                  rounded="sm"
                  style={{ aspectRatio: 1, backgroundColor: item.color }}
                />
              }
              item={item}
            >
              {item.label}
            </ComboboxCheckboxItem>
          )}
        </ComboboxListbox>
      </ComboboxContent>
    </Combobox>
  );
}

#
Creatable

We can combine filtering and controlled usage to build creatable comboboxes by allowing the user to add new entries on the fly.

App.tsx


"use client";
 
import {
  Combobox,
  ComboboxCheckboxItem,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
import { type Color, colors } from "./data";
import { useSet } from "./useSet";
 
export function App() {
  const [items, setItems] = useState(colors);
  const [value, { toggle }] = useSet<Color>([]);
 
  const [inputValue, setInputValue] = useState("");
  const filteredItems = inputValue
    ? [
        ...items.filter((color) =>
          color.label.toLowerCase().includes(inputValue.toLowerCase()),
        ),
        ...(items.find(
          (color) => color.label.toLowerCase() === inputValue.toLowerCase(),
        )
          ? []
          : [{ label: inputValue, new: true }]),
      ]
    : items;
 
  return (
    <Combobox
      inputValue={inputValue}
      isItemSelected={(item) => value.includes(item)}
      items={filteredItems}
      itemToLabel={(item) => item?.label || ""}
      onInputValueChange={setInputValue}
      onItemSelect={(value) => {
        if (value.new) {
          const newItem = { label: value.label };
          setItems((items) => [...items, newItem]);
          toggle(newItem);
 
          setInputValue("");
        } else {
          toggle(value);
        }
      }}
    >
      <ComboboxTrigger w="224">Select colors</ComboboxTrigger>
 
      <ComboboxContent>
        <ComboboxInput />
 
        <ComboboxListbox>
          {filteredItems.map((item) => (
            <ComboboxCheckboxItem item={item} key={item.label}>
              {item.new ? `Create "${item.label}"` : item.label}
            </ComboboxCheckboxItem>
          ))}
        </ComboboxListbox>
      </ComboboxContent>
    </Combobox>
  );
}

data.ts


export type Color = { label: string; new?: boolean };
 
export const colors: Color[] = [
  { label: "Ocean" },
  { label: "Blue" },
  { label: "Purple" },
  { label: "Red" },
  { label: "Orange" },
];

useSet.ts


import { useState } from "react";
 
export const useSet = <T>(initialValue: T[]) => {
  const [list, setList] = useState(initialValue);
  return [
    list,
    {
      toggle: (value: T) =>
        setList((prev) =>
          prev.includes(value)
            ? prev.filter((prevValue) => prevValue !== value)
            : [...prev, value],
        ),
    },
  ] as const;
};

#
Trigger

By default we use the Button component for the combobox trigger which accepts all of the existing button props.

#
Item

The ComboboxCheckboxItem and ComboboxRadioItem components accepts icon, addonBefore, addonAfter, and description props for additional content inside the items.

App.tsx


"use client";
 
import { Box } from "@optiaxiom/react";
import {
  Combobox,
  ComboboxCheckboxItem,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
import { type Color, colors } from "./data";
 
export function App() {
  const [value, setValue] = useState<Color[]>([]);
 
  return (
    <Combobox
      defaultItems={colors}
      isItemDisabled={(item) => Boolean(item.isDisabled)}
      isItemSelected={(item) => value.includes(item)}
      itemToLabel={(item) => (item ? item.label : "")}
      onItemSelect={(value) =>
        setValue((prev) =>
          prev.includes(value)
            ? prev.filter((v) => v !== value)
            : [...prev, value],
        )
      }
    >
      <ComboboxTrigger w="224">Select colors</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput />
        <ComboboxListbox>
          {(item) => (
            <ComboboxCheckboxItem
              icon={
                <Box
                  rounded="sm"
                  style={{ aspectRatio: 1, backgroundColor: item.color }}
                />
              }
              item={item}
            >
              {item.label}
            </ComboboxCheckboxItem>
          )}
        </ComboboxListbox>
      </ComboboxContent>
    </Combobox>
  );
}

#
Virtualized

We can use virtualization to improve performance when rendering a large number of items inside the combobox. Inside ComboboxListbox set children to a render prop to enable virtualization.


"use client";
 
import {
  Combobox,
  ComboboxCheckboxItem,
  ComboboxContent,
  ComboboxInput,
  ComboboxListbox,
  ComboboxTrigger,
} from "@optiaxiom/react/unstable";
import { useState } from "react";
 
const colors = Array.from({ length: 2000 }).map(
  (_, index) => `Color ${index + 1}`,
);
 
export function App() {
  const [value, setValue] = useState([colors[0]]);
 
  return (
    <Combobox
      defaultItems={colors}
      isItemSelected={(item) => value.includes(item)}
      onItemSelect={(value) =>
        setValue((prev) =>
          prev.includes(value)
            ? prev.filter((v) => v !== value)
            : [...prev, value],
        )
      }
    >
      <ComboboxTrigger w="224">Select colors</ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput />
        <ComboboxListbox>
          {(item) => (
            <ComboboxCheckboxItem item={item}>{item}</ComboboxCheckboxItem>
          )}
        </ComboboxListbox>
      </ComboboxContent>
    </Combobox>
  );
}

Prop
`defaultFilter` Return true/false for filtering items with the given search input. `(item: Item, inputValue: string) => boolean`
`defaultItems` The initial items we want to render in uncontrolled mode. `Item[]`
`defaultOpen` The initial open state in uncontrolled mode. `false \| true` Default: `false`
`inputValue` The input value in controlled mode. `string`
`isItemDisabled` Return true if items need to be marked as disabled and skipped from keyboard navigation. `(item: Item, index: number) => boolean`
`isItemSelected` Return true if item need to be marked as selected. `(item: Item, index: number) => boolean`
`items` The items we want to render in controlled mode. `Item[]`
`itemToLabel` Return a string representation of items if they are objects. Needed to show selected values inside triggers. `(item: Item) => string`
`onInputValueChange` Handler that is called when input value changes. `(inputValue: string) => void`
`onItemSelect` Handler that is called when an item is selected either via keyboard or mouse. `(value: Item) => void`
`onOpenChange` Handler that is called when the open state changes. `(open: boolean) => void`
`open` The open state in controlled mode. `false \| true`