Combobox

Combobox allows users to search and select a value from a dropdown list of options.

Usage

import { Combobox } from '@elegantui/forms';

Components

The Combobox component also includes a Combobox.Option component that allows you to display a list of options.

Basic Example

import { Combobox } from '@elegantui/forms';

export default function App() {
  const people = [
    { id: 1, name: 'Durward Reynolds', unavailable: false },
    { id: 2, name: 'Kenton Towne', unavailable: false },
    { id: 3, name: 'Therese Wunsch', unavailable: false },
    { id: 4, name: 'Benedict Kessler', unavailable: true },
    { id: 5, name: 'Katelyn Rohan', unavailable: false }
  ];

  const [person, setPerson] = React.useState(people[0]);
  const [query, setQuery] = React.useState('');

  const filteredPeople =
    query === ''
      ? people
      : people.filter((person) => {
          return person.name.toLowerCase().includes(query.toLowerCase());
        });

  return (
    <Combobox
      name='combobox'
      label='Combobox'
      value={person}
      onChange={(p) => setPerson(p)}
      inputDisplayValue={(p) => p?.name ?? ''}
      inputChangeHandler={(e) => setQuery(e.target.value)}
    >
      {filteredPeople.map((person) => (
        <Combobox.Option
          key={person.id}
          optionText={person.name}
          value={person}
        />
      ))}
    </Combobox>
  );
}

Filtering values

The inputChangeHandler prop provides a callback function with the change event as the arguemt and can be used to filter the list by accessing the value property of event.target.

Displaying selected value

The inputDisplayValue prop provides a callback function with the selected option as the argument and returns a string. The value returned from this callback function will be used as the display value.

Variants

Combobox component is available in six variants

import { Combobox } from '@elegantui/forms';

export default function App() {
  const people = [
    { id: 1, name: 'Durward Reynolds', unavailable: false },
    { id: 2, name: 'Kenton Towne', unavailable: false },
    { id: 3, name: 'Therese Wunsch', unavailable: false },
    { id: 4, name: 'Benedict Kessler', unavailable: true },
    { id: 5, name: 'Katelyn Rohan', unavailable: false }
  ];

  const [person, setPerson] = React.useState(people[0]);
  const [query, setQuery] = React.useState('');

  const filteredPeople =
    query === ''
      ? people
      : people.filter((person) => {
          return person.name.toLowerCase().includes(query.toLowerCase());
        });

  return (
    <Combobox
      name='combobox'
      label='Combobox'
      value={person}
      onChange={(p) => setPerson(p)}
      inputDisplayValue={(p) => p?.name ?? ''}
      inputChangeHandler={(e) => setQuery(e.target.value)}
      variant='primary' // 'default' | 'secondary' | 'success' | 'warning' | 'error'
    >
      {filteredPeople.map((person) => (
        <Combobox.Option
          key={person.id}
          optionText={person.name}
          value={person}
        />
      ))}
    </Combobox>
  );
}

Label

Combobox component renders a label for accessibility purposes. The value for the label can be provided using the label prop. If you would like to hide the label but still keep it accessible to screen readers you can pass a hideLabel prop.

import { Combobox } from '@elegantui/forms';

export default function App() {
  const people = [
    { id: 1, name: 'Durward Reynolds', unavailable: false },
    { id: 2, name: 'Kenton Towne', unavailable: false },
    { id: 3, name: 'Therese Wunsch', unavailable: false },
    { id: 4, name: 'Benedict Kessler', unavailable: true },
    { id: 5, name: 'Katelyn Rohan', unavailable: false }
  ];

  const [person, setPerson] = React.useState(people[0]);
  const [query, setQuery] = React.useState('');

  const filteredPeople =
    query === ''
      ? people
      : people.filter((person) => {
          return person.name.toLowerCase().includes(query.toLowerCase());
        });

  return (
    <Combobox
      name='combobox'
      label='Combobox'
      value={person}
      onChange={(p) => setPerson(p)}
      inputDisplayValue={(p) => p?.name ?? ''}
      inputChangeHandler={(e) => setQuery(e.target.value)}
      hideLabel
    >
      {filteredPeople.map((person) => (
        <Combobox.Option
          key={person.id}
          optionText={person.name}
          value={person}
        />
      ))}
    </Combobox>
  );
}

Disabled state

Combobox component can be disabled by using the disabled prop. This will disable the entire component. For disabling only certain options the disabled prop needs be passed to each Combobox.Option component individually.

import { Combobox } from '@elegantui/forms';

export default function App() {
  const people = [
    { id: 1, name: 'Durward Reynolds', unavailable: false },
    { id: 2, name: 'Kenton Towne', unavailable: false },
    { id: 3, name: 'Therese Wunsch', unavailable: false },
    { id: 4, name: 'Benedict Kessler', unavailable: true },
    { id: 5, name: 'Katelyn Rohan', unavailable: false }
  ];

  const [person, setPerson] = React.useState(people[0]);
  const [query, setQuery] = React.useState('');

  const filteredPeople =
    query === ''
      ? people
      : people.filter((person) => {
          return person.name.toLowerCase().includes(query.toLowerCase());
        });

  return (
    <Combobox
      name='combobox'
      label='Combobox'
      value={person}
      onChange={(p) => setPerson(p)}
      inputDisplayValue={(p) => p?.name ?? ''}
      inputChangeHandler={(e) => setQuery(e.target.value)}
      disabled
    >
      {filteredPeople.map((person) => (
        <Combobox.Option
          key={person.id}
          optionText={person.name}
          value={person}
          disabled={person.unavailable} // use this to disable only certain options
        />
      ))}
    </Combobox>
  );
}

Available Props

Combobox

Combobox.Option