Select

Select allows users to choose one option from a list of items in a Menu.

GitHubStorybook
yarn add @workday/canvas-kit-react
Sources
GitHubStorybook
Install
yarn add @workday/canvas-kit-react

Anatomy

Image of a Select Input in its default state.

  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

Alert: Please select a pizza size.

Error

Error: Please select a pizza size.

Props

Undocumented props are spread to the underlying <select> element.

NameTypeDefaultDescription
children*ReactElement<SelectOption, string | JSXElementConstructor<any>> | ReactElement<SelectOption, string | JSXElementConstructor<any>>[]The SelectOption children of the Select (must be at least two).
disabledboolean | undefinedfalseIf true, set the Select to the disabled state.
errorErrorType | undefinedThe type of error associated with the Select (if applicable).
onChange((e: ChangeEvent<HTMLSelectElement>) => void) | undefinedThe function called when the Select state changes.
valuestring | undefinedThe value of the Select.
themeEmotionCanvasTheme | undefined
growboolean | undefinedTrue if the component should grow to its container's width. False otherwise.
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef` and spread extra props to a root element.

Specifications

GivenWhenThen
given the 'Basic' story is rendered
    • it should not have any axe errors
    given the 'Basic' story is rendered
    • 'medium' is selected
    • it should be focused
    given the 'Basic' story is rendered
    • 'medium' is selected
    • it should have a value of 'medium'
    given the 'Alert' story is rendered
      • it should not have any axe errors
      given the 'Alert' story is rendered
      • 'medium' is selected
      • it should be focused
      given the 'Alert' story is rendered
      • 'medium' is selected
      • it should have a value of 'medium'
      given the 'Error' story is rendered
        • it should not have any axe errors
        given the 'Error' story is rendered
        • 'medium' is selected
        • it should be focused
        given the 'Error' story is rendered
        • 'medium' is selected
        • it should have a value of 'medium'
        given the 'Disabled' story is rendered
          • it should not have any axe errors
          given the 'Disabled' story is rendered
            • it should be disabled
            Source: Select.spec.ts

            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.

            Can't Find What You Need?

            Check out our FAQ section which may help you find the information you're looking for.

            FAQ Section