Combobox

Combobox 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 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. You can find more detailed information about the hook here.

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

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>
  );
}

useFilteredOptions hook

Example implementation

useFilteredOptions hook provides basic data handling for filtering.

import React, { useState } from 'react';
import { IntlMessageShape } from '@jutro/prop-types';
import { useTranslator } from '@jutro/locale';

type SelectValue = {
    id: string;
    label: IntlMessageShape;
    [index: PropertyKey]: unknown;
};

/**
 * @typedef {Object} FilterHookReturnObject
 * @property {TValue[]} filteredOptions - array of filtered options
 * @property {function} onSearch - function that takes the onSearch input event
 * and filters the options based on it
 * @property {function} resetFilter - used to reset the filtering for options,
 * after using filteredOptions array resets to initial one
 * @property {function} onAddNew - function that adds new value to the internal
 * options array inside the hook and calls appendToSelection that is responsible
 * for selecting this new value inside the dropdown
 */

/**
 * Helper hook for filtering options based on user input.
 *
 * @param {TValue[]} initialOptions - initial list of options in component
 * @param {function} createNewValue - function for constructing value object
 * from string
 * @param {function} appendToSelection - callback that is responsible for
 * appending value to the controlled list of selected values
 *
 * @returns {FilterHookReturnObject} - helpers for filtering purposes:
 * filtered options array, onAddNew and onSearch function to be supplied
 * to component and resetFilter function
 */
export const useFilteredOptions = <TValue extends SelectValue = SelectValue>(
    initialOptions: TValue[],
    createNewValue?: (value: string) => TValue,
    appendToSelection?: (value: TValue) => void
): {
    filteredOptions: TValue[];
    onSearch: (event: React.ChangeEvent<HTMLInputElement>) => void;
    resetFilter: () => void;
    onAddNew: (newValue: string) => void;
} => {
    const translator = useTranslator();
    const [query, setQuery] = useState('');
    const [options, setOptions] = useState(initialOptions);

    // Basic filtering. This part should be changed to cover your needs.
    const filteredOptions = options.filter(val =>
        translator(val.label)
            .trim()
            .toLowerCase()
            .includes(query.trim().toLowerCase())
    );

    // Function that should be passed to the Combobox onSearch prop.
    // It gets the value of the search term inside Combobox.
    const onSearch = (event: React.ChangeEvent<HTMLInputElement>) => {
        setQuery(event.target.value);
    };

    // Function that is responsible for clearing the query
    // only when the Combobox is on active browser tab.
    // Typically connected to Combobox onBlur.
    const resetFilter = () => {
        if (document.visibilityState === 'visible' && document.hasFocus()) {
            setQuery('');
        }
    };

    // Function responsible on adding new values to both
    // internal state of filtered items and external
    // controlled state value
    const onAddNew = (newValue: string) => {
        const valueTransformed = createNewValue?.(newValue);

        setQuery('');

        if (valueTransformed) {
            // adds the value to the internal state
            setOptions(prevOptions => [...prevOptions, valueTransformed]);
            // adds the value to the controlled state
            appendToSelection?.(valueTransformed);
        }
    };

    return { filteredOptions, onSearch, resetFilter, onAddNew };
};

Example implementation with asynchronous API calls

Asynchronous API calls are not handled inside the basic useFilteredOptions hook. For this purpose you might need to create your own implementation catered to your specific needs. This is an example of a custom hook for the Combobox component:

import React, { useEffect, useState } from 'react';

import { Combobox, ComboboxOption } from '@jutro/components';
import { useTranslator } from '@jutro/locale';
import { IntlMessageShape } from '@jutro/prop-types';

type SelectValue = {
    id: string;
    label: IntlMessageShape;
    [index: PropertyKey]: unknown;
};

const someAPICallback = async query => {
    console.log('calling the API');

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

    const result = new Promise(resolve => {
        setTimeout(
            () =>
                resolve(
                    CHARACTERS.filter(val =>
                        val.label
                            .trim()
                            .toLowerCase()
                            .includes(query.trim().toLowerCase())
                    )
                ),
            3000
        );
    });

    return result;
};

const useFilteredOptions = <TValue extends SelectValue = SelectValue>(): {
    filteredOptions: TValue[];
    onSearch: (event: React.ChangeEvent<HTMLInputElement>) => void;
    resetFilter: () => void;
    loading: boolean;
} => {
    const [query, setQuery] = useState('');
    const [filteredOptions, setFilteredOptions] = useState([]);
    const [loading, setLoading] = useState(true);

    useEffect(() => {
        setLoading(true);

        // This is a simple example only, API callback should be debounced
        // to ensure the async operation does not overlap with the query change. 
        someAPICallback(query).then((opts: TValue[]) => {
            setFilteredOptions(opts);
            setLoading(false);
        });
    }, [query]);

    // Function that should be passed to the Combobox onSearch prop.
    // It gets the value of the search term inside Combobox.
    const onSearch = (event: React.ChangeEvent<HTMLInputElement>) => {
        setQuery(event.target.value);
    };

    // Function that is responsible for clearing the query
    // only when the Combobox is on active browser tab.
    // Typically connected to Combobox onBlur.
    const resetFilter = () => {
        if (document.visibilityState === 'visible' && document.hasFocus()) {
            setQuery('');
        }
    };

    return { filteredOptions, onSearch, resetFilter, loading };
};

export const Welcome: React.FC = () => {
    const translator = useTranslator();
    const { filteredOptions, onSearch, resetFilter, loading } =
        useFilteredOptions();

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

note

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

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 greyed 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.

State	Description
Enabled	Indicates to the user that the element is enabled for interaction.
Focus	Indicates to the user which UI element in the system is focused.
Disabled	Indicates to the user that the input value can't be changed because of local factors. For example, a checkbox above the input field must be checked to access this input field. The user can take action to enable it by interacting with the page.
Error	Indicates that the user has made a validation error. Error text provides corrective feedback to users.
Read-only	Indicates to the user that the input value can't be changed because of outside factors. For example, lack of write access. The user can take action to enable it by, for example, contacting an administrator.
Display-only	The display-only state is used for two cases: A UI element is used in display mode. A UI element is displayed in edit mode, but is never editable. This state was called “read-only” before.

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 with 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.

note

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

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

warning

Passing child options to the Combobox component other than ComboboxOption is not supported. Although it might work, it might result in unexpected behaviors or be affected by changes introduced in future releases

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

Description

If true, component is rendered in disabled state.

Default value

false

displayOnly

Type

boolean

Description

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

Default value

false

hideLabel

Type

boolean

Description

If true, the label is not visible

Default value

false

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

Description

Position of the label.

Default value

top

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

Description

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

Default value

false

required

Type

boolean

Description

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

Default value

false

secondaryLabel

Type

IntlMessageShape

Description

Additional label associated with the select.

showPlaceholderAsOption

Type

boolean

Description

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

Default value

false

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

Description

If true, component is rendered in disabled state.

Default value

false

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)

Key	Used for
jutro-components.fields.Combobox.noResults	Message to display when no results are found
jutro-components.fields.Combobox.optionsAvailable	Display the number of results found
jutro-components.fields.Combobox.selected	For accessibility: used to identify selected options
jutro-components.fields.Combobox.notSelected	For accessibility: used to identify unselected options
jutro-components.fields.dropdowns.SelectTag.close	Description for the selected option removal
jutro-components.fields.dropdowns.SelectTag.expand	Description for the expand option when tags are collapsed
jutro-components.fields.ComboboxGeneric.expandButton	Expand button description

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

warning

1. SelectOption and ComboboxOption must only be used in the context of their respective 'parent' component. Although they might work in isolation, this is not a supported feature.
2. Select and MultipleSelect components are only intended to accept SelectOption components as children. Although they might be able to display or handle other types or HTML elements, this is not a supported feature.
3. Combobox and MultipleCombobox components are only intended to accept ComboboxOption components as children. Although they might be able to display or handle other types or HTML elements, that is not a supported feature.

Any usage of these components outside of their supported scope falls outside of the non-breaking changes commitment, as such usage is not considered a part of the components contract. These usages might result in unexpected behaviors or be affected by changes introduced in future releases.

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.

Component	Old location	New location
TypeaheadMultiSelectField	@jutro/components/TypeaheadMultiSelectField	@jutro/legacy/components/TypeaheadMultiSelectField

Codemods are available to automatically rename existing imports.