Combobox

The example below loads live from Storybook; open it in Storybook to use the controls. Start typing; the list opens and narrows as you type.

Live example, StorybookOpen in Storybook

Default

Combobox is a text input and a filtered list. The chevron opens the list; with a choice the cross clears it.

City

The list narrows as you type.

LightDark

Copy code

import { Combobox, Provider } from '@bigbang/ui';

const cities = ['Adana', 'Ankara', 'Antalya', 'Bursa', 'İstanbul', 'İzmir', 'Konya'].map((city) => ({
  value: city.toLocaleLowerCase('tr'),
  label: city,
}));

export default function Default() {
  return (
    <Provider locale="en-GB">
      <Combobox label="City" items={cities} placeholder="Search for a city" description="The list narrows as you type." className="max-w-80" />
    </Provider>
  );
}

Multiple choice

With multiple the choices stay in the field as chips. A chip’s cross, or Backspace in an empty input, removes a choice.

Cities

Ankara

İzmir

LightDark

Copy code

import { Combobox, Provider } from '@bigbang/ui';

const cities = ['Adana', 'Ankara', 'Antalya', 'Bursa', 'İstanbul', 'İzmir', 'Konya'].map((city) => ({
  value: city.toLocaleLowerCase('tr'),
  label: city,
}));

export default function Multiple() {
  return (
    <Provider locale="en-GB">
      <Combobox multiple label="Cities" items={cities} defaultValue={['ankara', 'izmir']} className="max-w-96" />
    </Provider>
  );
}

Adding options

With onCreate an “Add …” row appears for text that is not in the list. Return the new item and add it to items.

Tags

Type a tag that is not in the list to add it.

LightDark

Copy code

import { Combobox, Provider, type ComboboxItem } from '@bigbang/ui';
import { useState } from 'react';

export default function Creatable() {
  const [tags, setTags] = useState<ComboboxItem[]>([
    { value: 'design', label: 'Design' },
    { value: 'research', label: 'Research' },
    { value: 'writing', label: 'Writing' },
  ]);
  return (
    <Provider locale="en-GB">
      <Combobox
        multiple
        label="Tags"
        description="Type a tag that is not in the list to add it."
        items={tags}
        onCreate={(label) => {
          const item = { value: label.toLocaleLowerCase(), label };
          setTags((current) => [...current, item]);
          return item;
        }}
        className="max-w-96"
      />
    </Provider>
  );
}

Server results

When the server filters, pass filter={false}, read the query with onInputValueChange and set loading while it loads.

Server search

LightDark

Copy code

import { Combobox, Provider, type ComboboxItem } from '@bigbang/ui';
import { useEffect, useState } from 'react';

const cities = ['Adana', 'Ankara', 'Antalya', 'Bursa', 'İstanbul', 'İzmir', 'Konya'].map((city) => ({
  value: city.toLocaleLowerCase('tr'),
  label: city,
}));

export default function Async() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState<{ query: string; items: ComboboxItem[] } | null>(null);
  useEffect(() => {
    // Stands in for a server request.
    const timer = setTimeout(() => {
      setResults({ query, items: cities.filter((city) => city.label.toLocaleLowerCase('tr').includes(query.toLocaleLowerCase('tr'))) });
    }, 600);
    return () => clearTimeout(timer);
  }, [query]);
  return (
    <Provider locale="en-GB">
      <Combobox
        label="Server search"
        items={results?.items ?? []}
        filter={false}
        loading={results?.query !== query}
        onInputValueChange={setQuery}
        placeholder="Search for a city"
        className="max-w-80"
      />
    </Provider>
  );
}

Error

error makes the field invalid and reads the message with the input.

City* required

Choose a city.

LightDark

Copy code

import { Combobox, Provider } from '@bigbang/ui';

const cities = ['Adana', 'Ankara', 'Antalya', 'Bursa', 'İstanbul', 'İzmir', 'Konya'].map((city) => ({
  value: city.toLocaleLowerCase('tr'),
  label: city,
}));

export default function Invalid() {
  return (
    <Provider locale="en-GB">
      <Combobox label="City" items={cities} required error="Choose a city." className="max-w-80" />
    </Provider>
  );
}

Grouped options

items can also be a list of groups, each with a label and items. The list shows each group under its heading; a group with no match is hidden while searching.

Live example, StorybookOpen in Storybook

Light and dark mode

Colours come from semantic tokens; neither mode needs extra settings.

Light

City

The list narrows as you type.

Dark

City

The list narrows as you type.

Copy code

import { Combobox, Provider } from '@bigbang/ui';

const cities = ['Adana', 'Ankara', 'Antalya', 'Bursa', 'İstanbul', 'İzmir', 'Konya'].map((city) => ({
  value: city.toLocaleLowerCase('tr'),
  label: city,
}));

export default function Default() {
  return (
    <Provider locale="en-GB">
      <Combobox label="City" items={cities} placeholder="Search for a city" description="The list narrows as you type." className="max-w-80" />
    </Provider>
  );
}