Select

Examples​

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

With an initial value​

Example of how to set the basic Select component with an initial value assigned.

<Select
  label="Your favorite characters"
  initialValue={{ id: '1', label: 'Anakin' }}>
  <SelectOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
  <SelectOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
</Select>

No initial value​

Simple Select component without an initial value.

<Select label="Your favorite characters">
  <SelectOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
  />
  <SelectOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
</Select>

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

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

Disabled options​

Example of the Selectcomponent with some dropdown options disabled:

<Select
  label="Your favorite character"
  initialValue={{ id: '2', label: 'Luke' }}>
  <SelectOption
    value={{
      id: '1',
      label: 'Anakin',
    }}
    disabled={true}
  />
  <SelectOption
    value={{
      id: '2',
      label: 'Luke',
    }}
  />
  <SelectOption
    value={{
      id: '3',
      label: 'Yoda',
    }}
  />
  <SelectOption
    value={{
      id: '4',
      label: 'Solo',
    }}
    disabled={true}
  />
</Select>

DisplayOnly dropdown​

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

An example is shown below:

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

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

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

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

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

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

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:

export functionSelectRef() {
  const selectRef = useRef(null);

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

  return (
    <div>
      <Button
        label="Set focus on Select"
        onClick={setFocus}
      ></Button>
      <Select
        label="Get the focus from the button"
        ref={selectRef}
      >
        <SelectOption
          value={{
            id: '1',
            label: 'Option 1',
          }}
        />
        <SelectOption
          value={{
            id: '2',
            label: 'Option 2',
          }}
        />
      </Select>
    </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 SelectValidation() {
  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 (
    <Select
      label="Select option 2"
      stateMessages={validationMessages}
      onChange={onChange}>
      <SelectOption
        value={{
          id: '1',
          label: 'Option 1',
        }}
      />
      <SelectOption
        value={{
          id: '2',
          label: 'Option 2',
        }}
      />
      <SelectOption
        value={{
          id: '3',
          label: 'Option 3',
        }}
      />
      <SelectOption
        value={{
          id: '4',
          label: 'Option 4',
        }}
      />
      <SelectOption
        value={{
          id: '5',
          label: 'Option 5',
        }}
      />
    </Select>
  );
}

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 select variant of the dropdown enables users to select one value from a list of mutually exclusive options.

When to use​

There's a large number of options (6 or more) from which users can select only one value.

When not to use​

• The list of selections is complex enough to merit searching and filtering. Use the combobox instead.
• 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, select 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 or placeholder text.
4. Dropdown menu: Displays a list of options to choose from.

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.

Keep menu items concise​

Limit each dropdown option to one line of text. If the text is too long for one line, you can add an ellipsis (...) for overflow content, and accompany with a browser-based tooltip to show the full string. However, it's recommended that you avoid truncation if at all possible.

Do keep menu items concise.

Don't use long menu items that require truncation.

Cut filler words​

Cut filler words like “please” to reduce word and character counts and make content easier to absorb.

“Please” is often overused, so we reserve it for specific situations. For example:

• There's a problem that we can't help the user solve.
• The user is asked to do something inconvenient.
• The software is to blame for the situation.

If you're simply prompting a user to select an option from the dropdown menu, you wouldn't preface that with “please.”

Do eliminate filler words.

Don't use “please” unless the situation calls for it.

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.

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 select an employment status and this is a required field, you can use error text to guide the user to a solution: “Select an employment status.”

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, placeholder text, 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 select 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.

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

The following image illustrates dropdown select 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.

Code​

<Select label="This is a Select component">
  <SelectOption
    value={{
      id: '1',
      label: 'Option 1',
    }}
  />
  <SelectOption
    value={{
      id: '2',
      label: 'Option 2',
    }}
  />
</Select>

Import statement​

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

import { SelectOption } 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​

Select properties​

childrenrequired​

Type

SelectOption[]

Description

A list of options; only <SelectOption /> 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.

SelectOption 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​

No hooks are available for Select.

Translation keys​

There are no translations for Select.

For information on how to manage translations, see our section about Internationalization.

Custom behaviors​

Go to option starting with a specific character​

By pressing a key, the selection focus moves the the next option that starts with that character. If no option matches the condition, the focus will not be moved.

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 DropdownSelectField component?

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

  • DropdownSelectField

Changelog​

10.0.0​

New @jutro/components/Select component introduced.

The previous DropdownSelectFieldcomponent 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.