Select

Anatomy

1. Label: Title of the input.
2. Input Container: Rectangular container that houses the icon and placeholder text.
3. Placeholder Text (Optional): Placeholder text like “Select One” is typically displayed in the Select field. After the user makes a selection, the placeholder text is replaced with the user’s selection.
4. Icon: Caret icon positioned to the right of the container visually distinguishes this as a Select input.

Usage Guidance

• Clicking or tapping anywhere in a Select opens the Menu.
• A checkmark icon indicates which value is currently selected in the list.
• Each Menu option should be distinct. If the option isn’t discrete, combine it with another option.
• The list of Menu options should be sorted in a logical order alphabetically, chronologically, or by order of importance.

When to Use

• Use Select as a form element where users are only allowed to select one item from a list of more than 7 predefined options.
• Typically, Selects work best when the list is between 7 to 15 items to prevent overwhelming the user with too many options.

When to Use Something Else

• Consider using a Switch if the only options are yes or no.
• For a list between 2 to 7 predefined options, consider using Radio Buttons to select one option or Checkboxes to select multiple options. Radio and Checkbox groups display all options upfront and do not require the user to interact with the input to view the list of options.
• Use a Prompt when the number of list items is large or unknown. Prompts have search capabilities and folders which provide users with the means to browse options. Prompts can be configured to support single or multi-select.

Examples

Basic Example

Select should be used in tandem with Form Field to meet accessibility standards.

Disabled

Set the disabled prop of the Select to prevent users from interacting with it.

You may also set the disabled prop of the Select Option to prevent users from selecting that Option. Note that the value of a Select may be programmatically set to a disabled Option by setting the Select's value prop to the value of the disabled Option. The disabled Option, however, will remain unselectable by the user.

Ref Forwarding

Select supports ref forwarding. It will forward ref to its underlying <select> element.

Grow

Set the grow prop of the wrapping Form Field to true to configure the Select to expand to the width of its container.

The grow prop may also be applied directly to the Select if Form Field is not being used.

Label Position

Set the labelPosition prop of the wrapping Form Field to designate the position of the label relative to the Select. labelPosition accepts the following values:

• FormField.LabelPosition.Top (Default)
• FormField.LabelPosition.Left

Required

Set the required prop of the wrapping Form Field to true to indicate that the field is required. Labels for required fields are suffixed by a red asterisk.

Error States

Set the error prop of the wrapping Form Field to FormField.ErrorType.Alert or FormField.ErrorType.Error to set the Select to the Alert or Error state, respectively. You will also need to set the hintId and hintText props on the Form Field to meet accessibility standards.

The error prop may be applied directly to the Select with a value of Select.ErrorType.Alert or Select.ErrorType.Error if Form Field is not being used.

Alert

Error

Component API

ErrorType

Specifications

Accessibility Guidelines

Structure

• <select> tag with <option> tags for each option

Visual

• Ensure text exceeds a contrast ratio of 4.5:1 against the background to meet WCAG Success Criterion 1.4.3 for minimum contrast.
• Ensure keyboard focus is visually indicated and exceeds a contrast ratio of 3.0:1 against the background and prior state to meet WCAG Success Criterion 1.4.11 for non-text contrast.
• Select Button meets 3.0:1 contrast against background.

Interaction

• NOTE: All keyboard interactions are built-in for HTML <select> so no scripting is needed for keyboard navigation. Pressing tab on element visually prior to Select places focus on Select button. Pressing tab again moves focus to the next UI element.
• When pressing enter or space when focus is on the Select Button opens the listbox and places focus on the first option.
• Pressing enter when focus is on an option in the list selects the option.
• When a single-select listbox receives focus:
  • If none of the options are selected before the listbox receives focus, the first option receives focus. Optionally, the first option may be automatically selected.
  • If an option is selected before the listbox receives focus, focus is set on the selected option.
• Down Arrow: Moves focus to the next option. Optionally, in a single-select listbox, selection may also move with focus.
• Up Arrow: Moves focus to the previous option. Optionally, in a single-select listbox, selection may also move with focus.
• Escape: Closes the listbox and places focus back on the triggering button.
• Type-ahead is recommended for all listboxes, especially those with more than seven options:
  • Type a character: focus moves to the next item with a name that starts with the typed character.
  • Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.

Screen Reader

• If Select has no placeholder text, an aria-label is required to indicate what the Button does.

Content Guidelines

• The list of Menu items should be scannable, with concise labels written in title case. Don’t write sentences and omit articles (a, an, the) unless needed for clarity. For more detailed information on how to write Menu items, refer to the Drop-down Menus section of the Content Style Guide.
• Placeholder text for a Select must begin with the verb “Select”. Refer to the guidelines on Placeholder Text in the Content Style Guide for more tips on how to write placeholder text.