Combobox

Examples​

Check out the Usage section for details about how and when to use Combobox 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.

Combobox filtered by user input​

export function ComboWithFilter() {
  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 (
    <Combobox
      label="Select 1 option"
      secondaryLabel="Options filtered by user input"
      onSearch={onSearch}
      onBlur={resetFilter}>
      {filteredOptions.map(({ id, label }) => (
        <ComboboxOption
          key={id}
          value={{ id, label }}
        />
      ))}
    </Combobox>
  );
}

Combobox with initial value​

Define an initial value for the Combobox:

export function ComboWithInitial() {
  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 (
    <Combobox
      label="Select 1 option"
      secondaryLabel="Options filtered by user input"
      initialValue={CHARACTERS[2]}
      onSearch={onSearch}
      onBlur={resetFilter}>
      {filteredOptions.map(({ id, label }) => (
        <ComboboxOption
          key={id}
          value={{ id, label }}
        />
      ))}
    </Combobox>
  );
}

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 Combobox component.

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

Disabled options​

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

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

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

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

DisplayOnly dropdown​

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

An example is shown below:

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

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 ComboControlled() {
  const [updatedValue, setNewValue] = useState(null);

  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>
      <Combobox
        label="Choose values"
        secondaryLabel="This value will be passed to the list of options below"
        onChange={onChange}>
        {options}
      </Combobox>
      <br />
      <Combobox
        label="Changes with the above"
        value={updatedValue}>
        {options}
      </Combobox>
    </div>
  );
}

Clear previously selected options​

The user can always remove the options they have selected in a MultipleSelect or MultipleCombobox component. The Select and Combobox components, however, by default do not allow the user to clear a selected value. You can enable this feature using the placeholder and showPlaceholderAsOption properties - the provided placeholder will be available as the first option of the dropdown and, if the user selects it, it will clear the previous value they have selected.

You need to set these two properties as follows:

• placeholder cannot be empty
• showPlaceholderAsOption must be set to true.

See the example with the Combobox component:

<Combobox
  label="Your favorite character"
  initialValue={{ id: '1', label: 'Anakin' }}
  placeholder="Choose a character"
  showPlaceholderAsOption>
  <ComboboxOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
  <ComboboxOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
</Combobox>

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 Combobox component:

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

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

  return (
    <div>
      <Button
        label="Set focus on Combobox"
        onClick={setFocus}></Button>
      <Combobox
        label="Get the focus from the button"
        ref={selectRef}>
        <ComboboxOption
          value={{
            id: '1',
            label: 'Option 1',
          }}
        />
        <ComboboxOption
          value={{
            id: '2',
            label: 'Option 2',
          }}
        />
      </Combobox>
    </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 ComboValidation() {
  const [validationMessages, setValidationMessages] = useState({});

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

    if (newValue && newValue.label !== 'Option 2') {
      setValidationMessages({
        error: ['You must select option number 2'],
      });
    }
  }, []);

  return (
    <Combobox
      label="Select option 2"
      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',
        }}
      />
    </Combobox>
  );
}

Usage​

Overview​

The dropdown component presents users with a set of options from which they select. Dropdowns progressively disclose options, preventing users from seeing too much information at one time. They can also be used to group information. Dropdowns are always supported by a field label or title that is positioned before the control.

This component comes in four variants: select, multiple select, combobox, and multiple combobox.

The combobox variant of the dropdown enables users to filter longer lists to only the selections matching a query. The user can select one option from the list.

When to use​

• There's a large number of options (6 or more) from which users can select only one value.
• The list of selections is complex enough to merit searching and filtering.

When not to use​

• If the list of selections is not complex enough for a combobox, you can use the dropdown select.
• There's a small number of options (5 or fewer) from which users can choose. Use the radio group for small sets of mutually exclusive items.

Source: Nielsen Norman Group

Formatting​

Anatomy​

Anatomy of the dropdown component, combobox variant.

1. Label: Describes the purpose of the input field.
2. Help text (optional): Gives extra context or helps the user choose the right selection.
3. Dropdown input: Displays the user selected option. Users can type inside the input field to find an option that matches their query.
4. Dropdown menu: Displays a list of options to choose from.

Typeahead​

Jutro accommodates dropdown menus with typeahead input fields. Users can manually enter text to filter the dropdown items. This feature is useful for helping users select from a long list.

Dropdowns with typeahead enabled provide suggestions as users begin typing. Selections appear based on the characters that users have entered. The more characters that users input into the field, the more refined the list becomes.

Order of options​

When using the dropdown for sorting purposes, consider arranging options in order. For example:

• From most common to least common option
• From simplest to most complex operation
• From least to most risky option

The first option would appear at the top of the list.

Avoid arranging the list of options alphabetically unless it makes sense for your use case. Lists of countries and other known-item problems are often fine to alphabetize. However, you do need to ensure that users will know unambiguously the name of their selection.

Source: Nielsen Norman Group

Content​

General writing guidelines​

• Use sentence case for all aspects of designing Guidewire product interfaces. Don't use title case.
• Use present tense verbs and active voice in most situations.
• Use common contractions to lend your copy a more natural and informal tone.
• Use plain language. Avoid unnecessary jargon and complex language.
• Keep words and sentences short.

Include a label​

Place the dropdown label outside of the field so that it's always visible. A dropdown without a label is not accessible.

Don't replace field labels with in-field placeholder text. This hurts usability and has many negative consequences.

Do position a permanent label outside the field.

Don't use placeholder text as a replacement for the field label.

Add help text if it's meaningful​

Use help text to show context and communicate what to select or how to select an option. Here are some examples of what you might include in help text:

• An overall description of the dropdown options
• Hints that assist the user in choosing the right selection
• More context for why a user needs to make a selection

Only use help text for pertinent information. Avoid using help text that simply restates the same information that appears in the label.

Use sentence case for help text. Write 1-2 short, complete sentences that end with a period.

Do use help text to show context.

Don't use help text to simply restate the same information that appears in the label.

Don't use placeholder text​

Don't put placeholder text in the text entry field. Placeholder text strains users' short-term memory because it disappears once a value is entered. It also poses additional burdens for users with visual and cognitive impairments.

Instead, place hints and instructions outside of the field.

The input field for combobox follows the content guidelines for text fields.

Source: Nielsen Norman Group

Do place hints and instructions outside of the field.

Don't add placeholders to text entry fields.

Use error text to guide users​

Error message text tells a user how to fix the error. In the case of the dropdown, errors are often related to something that must be fixed for in-line validation. For example, if someone doesn't input the make of their vehicle and this is a required field, you can use error text to guide the user to a solution: “Select the make of your vehicle.”

Use sentence case for error text. Write 1-2 short, complete sentences that end with a period.

Do use error text to guide the user and show them a solution.

Don't write ambiguous error messages or leave users guessing as to how to resolve a problem.

Mark required fields​

Use an asterisk (*) to indicate required fields. The asterisk precedes the field label. This helps users to easily locate which fields are required by scanning just the left-most character of the label.

Do use an asterisk to indicate that a field is required.

Don't use an asterisk to denote anything that is optional.

Use sentence case​

Field labels and menu items appear in sentence case.

Refer to the UI text style guide for more information on how to implement sentence case.

Do use sentence case.

Don't use title case.

Behaviors​

States​

The combobox variant appears with no value (default), placeholder text, or a filled input.

Visual	State	Description
	No value (default)	Indicates to the user that no value has been selected and there is no placeholder.
	Placeholder	Indicates to the user that no value has been selected. The placeholder is grayed out.
	Filled input	Indicates to the user that the input is filled with data.

Combobox also has interactive states for enabled, focus, disabled, error, read-only, and display-only.

The following image illustrates combobox interactive states.

Interactions​

Mouse​

Users can interact with this element by clicking in the area inside border.

Keyboard​

The dropdown is expanded and collapsed using the Spacebar. Users navigate through the options using the arrow keys and select by means of the Spacebar or Enter key.

Screenreader​

The aria-labelledby establishes a programmatic association between the input field and its label. The WAI-ARIA attribute of aria-autocomplete='list' communicates that a list of choices will appear from which the user can choose, but the edit box retains focus. Selecting the 'required' option in Storybook adds both the 'required' and 'aria-required="true"' attributes to the input field.

Accessibility​

This component adheres to the following criteria for color and zoom accessibility:

• Color: The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.0 AA requirements.
• Zoom: All content is visible and functional up to and including a zoom factor of 200%.

This component has been validated to meet the WCAG 2.0 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance. When using this component within your application:

• Assist users in understanding the content by avoiding very long option names.
• Avoid using implicitly focusable elements such as buttons, checkboxes and links, or implicitly semantic content such as headings within your dropdown components.

Code​

export function ComboWithFilter() {
  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 (
    <Combobox
      label="Select 1 option"
      secondaryLabel="Options filtered by user input"
      onSearch={onSearch}
      onBlur={resetFilter}>
      {filteredOptions.map(({ id, label }) => (
        <ComboboxOption
          key={id}
          value={{ id, label }}
        />
      ))}
    </Combobox>
  );
}

Import statement​

import { Combobox } from '@jutro/components';

import { ComboboxOption } from '@jutro/components';

import { useFilteredOptions } from '@jutro/components';

Component contract​

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties​

Combobox properties​

childrenrequired​

Type

ComboboxOption[]

Description

A list of options; only <ComboboxOption /> components should be used.

labelrequired​

Type

IntlMessageShape

Description

The label associated with the component. Also passed as a default value to 'aria-label'.

className​

Type

string

Description

CSS class passed to root element of the component

disabled​

Type

boolean

Default value

false

Description

If true, component is rendered in disabled state.

displayOnly​

Type

boolean

Default value

false

Description

If true, displays the component value as a plain text.

hideLabel​

Type

boolean

Default value

false

Description

If true, the label is not visible

initialValue​

Type

valueShape[]: [{id: string, label: string}]

Description

Initial value of input. If value prop is specified along with this prop, this prop's value is discarded.

labelPosition​

Type

top | left

Default value

top

Description

Position of the label.

name​

Type

string

Description

A string specifying a name for the input. It is used also to include it on the event parameter of the onChange function

onBlur​

Type

func

Description

onBlur callback.

onChange​

Type

func

Description

onChange callback. Gets event as first argument and modified value as a second argument

onFocus​

Type

func

Description

onFocus callback.

placeholder​

Type

string

Description

Placeholder to display on an empty component

readOnly​

Type

boolean

Default value

false

Description

If true, component is rendered in read-only state, for value as a plain text consider using displayOnly

required​

Type

boolean

Default value

false

Description

If true, component is rendered as required and label has asterisk.

secondaryLabel​

Type

IntlMessageShape

Description

Additional label associated with the select.

showPlaceholderAsOption​

Type

boolean

Default value

false

Description

Renders the placeholder (when provided) as an option to allow unselecting the component

stateMessages​

Type

`{error: string[]}`

Description

Object with input state and messages that should be shown for current state

tooltip​

Type

`{ text: IntlMessageShape, trigger: string }`

Description

Tooltip props object: text - to show tooltip content, trigger - to set tooltip trigger

value​

Type

`{valueShape: {id: string, label: string}}`

Description

Value of the component. Takes precedence over initialValue. If this prop is passed, component works in controlled mode and its value will change only if this prop changes.

ComboboxOption properties​

className​

Type

string

Description

CSS class passed to root element of the component

disabled​

Type

boolean

Default value

false

Description

If true, component is rendered in disabled state.

value​

Type

valueShape[]: [{id: string, label: string}]

Description

Value of the component.

Hooks​

useFilteredOptions hook provides the mechanisms to handle the options displayed based on user input.

Parameters received:

• initialOptions: TValue[]. Initial list of options in the component without any filter applied

Output:

An object with:

• filteredOptions: TValue[]. Array with the options resulting from applying the filter
• onSearch: function. Function that takes the onSearch input event and filters the options based on it. This can be assigned to the
  onSearch event of the component.
• resetFilter: function. Used to reset the options filtering, setting filteredOptions array to its initial value

import {Combobox, ComboboxOption, useFilteredOptions} from '@jutro/components

export function ComboWithFilter() {
  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 (
    <Combobox
      label="Select 1 option"
      secondaryLabel="Options filtered by user input"
      onSearch={onSearch}
      onBlur={resetFilter}
    >
      {filteredOptions.map(({ id, label }) => (
        <ComboboxOption
          key={id}
          value={{ id, label }}
        />
      ))}
    </Combobox>
  );
}

Translation keys​

These are the translation keys associated with the Combobox component. (Shared with MultipleCombobox)

Custom behaviors​

Clear selected value​

By default, the Combobox does not allow the user to clear the component value. You can enable this feature using the placeholder and showPlaceholderAsOption properties - the provided placeholder will be available as the first option of the dropdown and, if the user selects it, it will clear the previous value they have selected.

Children​

All dropdown related components define the list of available options through the children property of ReactNode type. You can use only the following subcomponents as children:

• SelectOption in Select and MultipleSelect
• ComboboxOption in Combobox and MultipleCombobox

Escape hatches​

For more information, see our documentation about escape hatches.

The following options are available:

• Design Tokens
• className property
• Passing native HTML attributes
• Ref with imperative handlers
• Native event property

Ref with imperative handlers​

Jutro inputs have implemented imperative handlers as a mechanism to provide access to some common native features that might be useful for you. The following features are available:

• Set focus to allow you to set the user focus into a specific component

• Blur to remove the focus from the component

• Scroll to the component so that you can take the user to a specific area of the page.

These features are provided through the ref property, which exposes them as follows:

    const componentRef = useRef(null);

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

    const removeFocus = () => {
        componentRef?.current.blur();
    }

    const scrollToComponent = () => {
        componentRef?.current.scrollIntoView();
    }

    <Component ref={componentRef}>

More options might be included in the future.

Disabled, displayOnly and readOnly precedence​

If two or more of the properties disabled, displayOnly, and readOnly are set to true at the same time, the precedence is as follows:

displayOnly > readOnly > disabled

User input validation​

Although some Jutro components might provide complementary features or a helper function to facilitate the validation process, it is your responsibility as a developer to handle the validation of any user input (using or not using the complementary helpers) and to decide what error messages to show.

Jutro components behave based on the developer implementation.

When are error messages displayed?

Error messages are only displayed when you pass them to the component through the stateMessages property. This property receives an object with the following content:

{
  error: ['error message 1', 'error message 2', 'error message N'];
}

The component displays every error message provided in the same order as in the array.

When does validation occur?

This is your decision as a developer. As components do not determine when the validation is performed or when the error must be displayed, you need to implement the logic to handle it according to the project requirements, for example while the user is editing the content, when the component loses focus, and on form submission.

Legacy information​

Are you using the legacy TypeaheadMultiSelectField component?

• To view documentation for the old components, switch to a version of the documentation older than 10.0.
• These legacy components are also available in Storybook:

  • TypeaheadMultiSelectField

Changelog​

10.0.0​

New @jutro/components/Combobox component introduced.

The previous TypeaheadMultiSelectField component was deprecated and moved to the @jutro/legacy package. To view its documentation, switch to a version of the documentation older than 10.0.

Codemods are available to automatically rename existing imports.