Skip to main content

Select

Select 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 Select, and the specific tabs for details on the features that the component provides.

note

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

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>
  );
}
Legal and Support Information
Copyright © 2001-2024 Guidewire Software, Inc.