Pharos
JSTOR's Design System
 Getting started Help FAQs DocumentationDevelopment GitHub JSTOR LogosTypographyColorImageryIconographyElevationVoice and toneJSTOR termsWeb elementsGrammar and styleEditing checklistAlertButtonBreadcrumbCheckboxCheckbox groupCoach MarkComboboxDropdown menuDropdown menu navFooterHeaderHeadingIconImage cardInput groupLayoutLinkLoading spinnerModalMultiselect dropdownPaginationPillPopoverProgress barRadio buttonRadio groupSelectSheetSidenavSliderSwitchTableTabsToastTooltipText inputTextareaToggle button groupOverviewAlias colorsGlobal colorsFont familyFont sizeFont weightLine heightElevationRadiusSpacingTransitionsType scaleType styles
Skip to main navigation
Combobox
Comboboxes combine text inputs and dropdowns. The text input is used for filtering the options, while the dropdown allows the selecting of options.
Example
I am a combobox

See live code examples in Storybook
Usage

Clicking the dropdown arrow button will show all items. Typing in the text input will filter the list.

Entering custom values is not currently supported.

Best practices
Dos
  • Make sure the label clearly indicates to the user what kind of input is expected of them
  • Labels need to describe the purpose of the form control and must be used for all text inputs
  • Placeholder text should be a word or short phrase that demonstrates the expected type of data, rather than an explanatory message
  • Options shown in the dropdown are short and concise
Don'ts
  • Do not use placeholder text as a replacement for labels
  • Do not use for a short list of options, use a select component instead
Content guidelines Labels
  • The label needs to be helpful in telling the user what is expected of them, but they do not need to be instructive
  • Labels are placed above the Combobox
  • Labels are to be written in sentence case and should only be 1-3 words long
Placeholder text

Placeholder text is shown inside the text input to help users know what information they can enter.

  • Field placeholder text is used for supplementary information
  • The text should be written as examples instead of instructions
States Default

The default state - when no other state attribute is assigned to the Combobox.

Combobox label
Disabled

Display this state when the Combobox is non-interactive.

Combobox label
Required

This state signifies a mandatory response from the user.

Combobox label
Error

Display this state when a user has encountered an error with their input. This could be if they didn't fill out a required field, or the information provided does not meet validation requirements.

Combobox label
Accessibility Relevant WCAG guidelines
  • 1.3.5 Identify Input Purpose AA
  • 4.1.2 Name, Role, Value A
Importance
  • Combo boxes are used as a text field that has a list of pre-populated dropdown options. For this specific example, we are looking at a combobox with autocomplete.
Code expectations
  • Example of a combobox with an autocomplete dropdown list (via w3c)
  • The ComboBox uses the aria-expanded, aria-selected, aria-disabled, aria-haspopup, aria-owns, aria-activedescendant and aria-hidden properties on the nested elements depending on the current state of the component and its options.
  • The ComboBox uses the listbox role. Each item from the popup list has an option role.
  • To move the focus to the current keyboard navigation position, the component uses the aria-activedescendant approach.
Expected actions Accessibility best practices for labels:
  • Labels must be visible when an input gets focus
  • Labels must be announced to the screen reader on focus
  • Use sentence case
Screen reader
  • Reads: "label it is given, popup combobox"
  • When expanded it reads: "element name, 1 (or respective number), of X ("X" representing total number).
Keyboard
  • On textbook
    • Down arrow
      • Opens dropdown if nothing is typed in
      • If something is typed in it will put focus on the first suggestion
    • Alt + down arrow
      • Opens selection list without changing focus
    • Up arrow
      • If field is populated, moves focus to the last selection
      • If nothing is in field, first opens the list of selections then goes to the bottom
    • Enter
      • Selects the suggestion/closes the box
    • Esc
      • loses the box if the suggestion box is expanded