Skip to main content

MultipleCombobox

MultipleCombobox in Storybook
note

There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.

Examples​

Check out the Usage section for details about how and when to use MultipleCombobox and the specific tabs for details on the features that the component provides.

The useFilteredOptions hook is used to implement the filter mechanism based on user input. However, for clarity and simplicity it is not included in some examples. Refer to other examples for details on how to use it.

note

Most of the features and properties of the four provided Dropdown components do not have usage differences. Some examples from other components might be relevant for MultipleCombobox too.

Combobox filtered by user input​

export function MultipleComboWithFilter() {
  const CHARACTERS = [
    { id: '1', label: 'Anakin Skywalker' },
    { id: '2', label: 'Luke Skywalker' },
    { id: '3', label: 'Master Yoda' },
    { id: '4', label: 'Han Solo' },
  ];

  const { filteredOptions, onSearch, resetFilter } =
    useFilteredOptions(CHARACTERS);

  return (
    <MultipleCombobox
      label="Select options"
      secondaryLabel="Options filtered by user input"
      onSearch={onSearch}
      onBlur={resetFilter}>
      {filteredOptions.map(({ id, label }) => (
        <ComboboxOption
          key={id}
          value={{ id, label }}
        />
      ))}
    </MultipleCombobox>
  );
}

Combobox with initial value​

Define an initial value for the MultipleCombobox:

export function MultipleComboWithInitial() {
  const CHARACTERS = [
    { id: '1', label: 'Anakin Skywalker' },
    { id: '2', label: 'Luke Skywalker' },
    { id: '3', label: 'Master Yoda' },
    { id: '4', label: 'Han Solo' },
  ];

  const { filteredOptions, onSearch, resetFilter } =
    useFilteredOptions(CHARACTERS);

  return (
    <MultipleCombobox
      label="Select options"
      secondaryLabel="Options filtered by user input"
      initialValue={[CHARACTERS[2], CHARACTERS[3]]}
      onSearch={onSearch}
      onBlur={resetFilter}>
      {filteredOptions.map(({ id, label }) => (
        <ComboboxOption
          key={id}
          value={{ id, label }}
        />
      ))}
    </MultipleCombobox>
  );
}

Disabled dropdown or options​

You can disable completely any of the dropdown components by setting the disabled property to true. You can also disable only the specific options using the disabled property of the SelectOption and ComboboxOption components. In case that the whole component is disabled, the disabled property of the options does not have any effect.

Disabled dropdown​

Example of a disabled dropdown component using the MultipleCombobox component.

<MultipleCombobox
  label="Your favorite character"
  initialValue={[{ id: '1', label: 'Anakin' }]}
  disabled={true}>
  <ComboboxOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
  <ComboboxOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
</MultipleCombobox>

Disabled options​

Example of how to disable some dropdown options using the MultipleCombobox component.

export function MultipleComboWithDisabled() {
  const CHARACTERS = [
    { id: '1', label: 'Anakin Skywalker' },
    { id: '2', label: 'Luke Skywalker', unavailable: true },
    { id: '3', label: 'Master Yoda' },
    { id: '4', label: 'Han Solo', unavailable: true },
  ];

  const { filteredOptions, onSearch, resetFilter } =
    useFilteredOptions(CHARACTERS);

  return (
    <MultipleCombobox
      label="Select options"
      secondaryLabel="Options filtered by user input"
      onSearch={onSearch}
      onBlur={resetFilter}>
      {filteredOptions.map(({ id, label, unavailable }) => (
        <ComboboxOption
          key={id}
          value={{ id, label }}
          disabled={unavailable}
        />
      ))}
    </MultipleCombobox>
  );
}

DisplayOnly dropdown​

By setting the displayOnly property to true, the component value will be displayed as plain text.

An example is shown below:

<MultipleCombobox
  label="Your favorite characters (Multiple Combobox component)"
  initialValue={[{ id: '1', label: 'Anakin' }]}
  displayOnly={true}>
  <ComboboxOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
</MultipleCombobox>

Controlled component​

This is a common behavior for all of the dropdown components: when the value property is set, the user cannot directly modify the component, it will be managed entirely by the developer implementation.

This example is applicable to all dropdown components:

export function MultiComboControlled() {
  const [updatedValue, setNewValue] = useState([]);

  const onChange = (e, newValue) => {
    setNewValue(newValue);
  };

  const options = [
    <ComboboxOption
      value={{
        id: '1',
        label: 'Option 1',
      }}
    />,
    <ComboboxOption
      value={{
        id: '2',
        label: 'Option 2',
      }}
    />,
    <ComboboxOption
      value={{
        id: '3',
        label: 'Option 3',
      }}
    />,
    <ComboboxOption
      value={{
        id: '4',
        label: 'Option 4',
      }}
    />,
    <ComboboxOption
      value={{
        id: '5',
        label: 'Option 5',
      }}
    />,
  ];

  return (
    <div>
      <MultipleCombobox
        label="Choose values"
        secondaryLabel="This value will be passed to the list of options below"
        onChange={onChange}>
        {options}
      </MultipleCombobox>
      <br />
      <MultipleCombobox
        label="Changes with the above"
        value={updatedValue}>
        {options}
      </MultipleCombobox>
    </div>
  );
}

Set focus on the dropdown​

Using the ref property and the imperative handlers provided ('focus', 'blur' and 'scrollIntoView') it is possible to perform different native actions. An example is to set the focus on the component.

This is an example using MultipleCombobox component:

export function MultiComboRef() {
  const selectRef = useRef(null);

  const setFocus = (e) => {
    selectRef?.current?.focus();
  };

  return (
    <div>
      <Button
        label="Set focus on Select"
        onClick={setFocus}></Button>
      <MultipleCombobox
        label="Get the focus from the button"
        ref={selectRef}>
        <ComboboxOption
          value={{
            id: '1',
            label: 'Option 1',
          }}
        />
        <ComboboxOption
          value={{
            id: '2',
            label: 'Option 2',
          }}
        />
      </MultipleCombobox>
    </div>
  );
}

Component validation​

The dropdown components do not handle the validation process, but you can handle the error status and the messages to be displayed using the stateMessages property.

The state messages logic works for all dropdown components, below is an example of MultipleSelect:

export function MultiComboValidation() {
  const [validationMessages, setValidationMessages] = useState({});

  const onChange = useCallback((e, newValue) => {
    setValidationMessages({});

    if (newValue && newValue.length < 2) {
      setValidationMessages({
        error: ['At least 2 options must be selected'],
      });
    }
  }, []);

  return (
    <MultipleCombobox
      label="Select at least 2 options"
      stateMessages={validationMessages}
      onChange={onChange}>
      <ComboboxOption
        value={{
          id: '1',
          label: 'Option 1',
        }}
      />
      <ComboboxOption
        value={{
          id: '2',
          label: 'Option 2',
        }}
      />
      <ComboboxOption
        value={{
          id: '3',
          label: 'Option 3',
        }}
      />
      <ComboboxOption
        value={{
          id: '4',
          label: 'Option 4',
        }}
      />
      <ComboboxOption
        value={{
          id: '5',
          label: 'Option 5',
        }}
      />
    </MultipleCombobox>
  );
}
Legal and Support Information
Copyright © 2001-2024 Guidewire Software, Inc.