Skip to main content
Kaleidoscope

Combobox

HW
BL

A searchable dropdown that allows users to filter and select from a list of options with typeahead functionality.

Default

A standard Combobox with search functionality. Users can type to filter options and select from the filtered list.

Editable example
() => {
  const [value, setValue] = React.useState(null);
  const options = [
    "Nautilus",
    "Octopus",
    "Squid",
    "Cuttlefish",
    "Belemnite",
    "Ammonite",
    "Finned Octopus",
    "Vampire Squid",
    "Bobtail Squid",
    "Argonaut",
    "Plectronoceras"
  ];

  const search = (inputValue) => {
    return options.filter(option =>
      option.toLowerCase().indexOf(inputValue.toLowerCase()) >= 0
    );
  };

  return (
    <Combobox
      value={value}
      onChange={setValue}
      options={search}
      getOptionKey={(option) => option}
      getOptionLabel={(option) => option}
      renderInput={(props) => (
        <TextInput
          label="Favorite cephalopod"
          placeholder="Choose a cephalopod"
          {...props}
        />
      )}
    />
  );
}

Best practices

  1. Use Combobox when you have a large list of options (10+ items) that would benefit from search/filtering functionality.
  2. For smaller lists (4-10 items), consider using a component instead.
  3. Always provide meaningful placeholder text that indicates what users should search for.
  4. Use descriptive labels that clearly communicate the purpose of the selection.
  5. Consider using custom option rendering for complex data structures or when you need to display additional information.

Loading state

Show a loading spinner when options are being fetched asynchronously.

Editable example
<Combobox
  value={null}
  onChange={() => {}}
  options={{ isLoading: true }}
  getOptionKey={() => ""}
  getOptionLabel={() => ""}
  renderInput={(props) => (
    <TextInput label="" labelHidden {...props} />
  )}
/>

Custom option rendering

Use the renderOption prop to customize how each option is displayed. This is useful for showing additional information or using custom components like tokens.

Editable example
() => {
  const [value, setValue] = React.useState(null);
  const options = [
    "Nautilus",
    "Octopus",
    "Squid",
    "Cuttlefish",
    "Belemnite",
    "Ammonite",
    "Finned Octopus",
    "Vampire Squid",
    "Bobtail Squid",
    "Argonaut",
    "Plectronoceras"
  ];

  const search = (inputValue) => {
    return options.filter(option =>
      option.toLowerCase().indexOf(inputValue.toLowerCase()) >= 0
    );
  };

  return (
    <Combobox
      value={value}
      onChange={setValue}
      options={search}
      getOptionKey={(option) => option}
      getOptionLabel={(option) => option}
      renderInput={(props) => (
        <TextInput
          label="Favorite cephalopod"
          placeholder="Choose a cephalopod"
          {...props}
        />
      )}
      renderOption={(option) => (
        <Token type="text" name={option} />
      )}
      isOptionDisabled={(option) => options.indexOf(option) < 3}
    />
  );
}

Clear button

Add a clear button to allow users to easily reset their selection. The clear button only appears when a value is selected.

Editable example
() => {
  const [value, setValue] = React.useState(null);
  const options = [
    "Nautilus",
    "Octopus",
    "Squid",
    "Cuttlefish",
    "Belemnite",
    "Ammonite",
    "Finned Octopus",
    "Vampire Squid",
    "Bobtail Squid",
    "Argonaut",
    "Plectronoceras"
  ];

  const search = (inputValue) => {
    return options.filter(option =>
      option.toLowerCase().indexOf(inputValue.toLowerCase()) >= 0
    );
  };

  return (
    <Combobox
      value={value}
      onChange={setValue}
      options={search}
      getOptionKey={(option) => option}
      getOptionLabel={(option) => option}
      renderInput={(props) => (
        <TextInput
          label="Favorite cephalopod"
          placeholder="Choose a cephalopod"
          {...props}
        />
      )}
      renderClearButton={(props) => (
        <IconButton size={ButtonSize.XSmall} {...props} />
      )}
    />
  );
}

Disabled options

Use the isOptionDisabled prop to disable specific options that shouldn't be selectable.

Editable example
() => {
  const [value, setValue] = React.useState(null);
  const options = [
    "Nautilus",
    "Octopus",
    "Squid",
    "Cuttlefish",
    "Belemnite",
    "Ammonite",
    "Finned Octopus",
    "Vampire Squid",
    "Bobtail Squid",
    "Argonaut",
    "Plectronoceras"
  ];

  const search = (inputValue) => {
    return options.filter(option =>
      option.toLowerCase().indexOf(inputValue.toLowerCase()) >= 0
    );
  };

  return (
    <Combobox
      value={value}
      onChange={setValue}
      options={search}
      getOptionKey={(option) => option}
      getOptionLabel={(option) => option}
      renderInput={(props) => (
        <TextInput
          label="Favorite cephalopod"
          placeholder="Choose a cephalopod"
          {...props}
        />
      )}
      isOptionDisabled={(option) =>
        ["Belemnite", "Ammonite", "Plectronoceras"].includes(option)
      }
    />
  );
}

Custom no options text

Override the default "No results found" message with custom text when no options match the search.

Editable example
() => {
  const [value, setValue] = React.useState(null);
  const options = [
    "Nautilus",
    "Octopus",
    "Squid",
    "Cuttlefish"
  ];

  const search = (inputValue) => {
    return options.filter(option =>
      option.toLowerCase().indexOf(inputValue.toLowerCase()) >= 0
    );
  };

  return (
    <Combobox
      value={value}
      onChange={setValue}
      options={search}
      getOptionKey={(option) => option}
      getOptionLabel={(option) => option}
      renderInput={(props) => (
        <TextInput
          label="Favorite cephalopod"
          placeholder="Choose a cephalopod"
          {...props}
        />
      )}
      noOptionsText="No cephalopods found matching your search"
    />
  );
}

Accessibility

  • The Combobox follows ARIA 1.2 combobox pattern for proper screen reader support
  • Keyboard navigation is supported with arrow keys, Enter, Escape, and Tab
  • The component automatically manages focus states and announcements
  • Clear button includes proper ARIA labels for screen readers
  • Loading states are announced to assistive technology
  • Disabled options are properly marked and announced