Combo Box

This component is used when you require users to make one or more selections from a list

General

React

Take note that for Combo Box component, you may use our React version instead. Do check out our SGDS React Storybook for further documentation.

Example

Default combo box

            
                        HTML
                    
                        React
                    
                        Web Component
                    
                        <head>
  
  <script 
  type="module" 
  src="https://cdn.jsdelivr.net/npm/@govtechsg/sgds-web-component@2.1.2/components/ComboBox/index.umd.js">
  </script>
</head>
<body>
  <div style="height:100px;">
    <sgds-combo-box 
      label="Items" 
      hinttext="" 
      name="undefined" 
      placeholder="ComboBox" 
      value="" 
      close="default"
      menulist="[
      &quot;Apple&quot;,
      &quot;Pear&quot;,
      &quot;Durian&quot;]"
    >
    </sgds-combo-box>
  </div>
  <!-- Add fluid attribute for full width banner -->
  <!-- 
      <sgds-masthead fluid></sgds-masthead> 
  -->
</body>
                    
                            View on React storybook
                        
                        View on Web component storybook

Anatomy

Text label: Inform users of what data should be put into the field, labels must always be outside of the text field.
Hint text: Serve to guide to the user, helping to inform users as to what kind of data they are required to enter.
Option text: Options on what you want users to select.
Dropdown icon: A combo box has a chevron-down icon to the right of the text label to indicate that it will toggle content.

Spacing

Within the combo box

Ensure that there is a min of 8px vertical spacing and 16px horizontal spacing on the left and right.

Usage guidelines

Best practices:

Keep menu items short and concise. Long menu items that cause text to wrap to multiple lines are discouraged.
Error messages should guide the user and showing them a solution instead of only stating what went wrong.

Combo box should be used when:

Displaying multiple related options with a common parent context
You have a large list of choices and need to save space in your interface

Combo box should not be used when:

Displaying a 'yes' or 'no' selection. Instead, use radio buttons.

Usability guidelines

Ensure that the labels are clear
This will allow users to understand the purpose of the selection. Labels should also be placed outside the combobox to remain visible at all times.

Use a default option whenever possible
This could be an option such as "Any". Only use the empty selection if a default option does not make sense.

Behaviour
Make use of hint texts or tooltips if your user is highly unfamiliar with the content in the combo box, or if the data is especially complex.

Accessibility guidelines

Aria attributes

When a combobox receives focus, DOM focus is placed on the combobox element.
If the combobox has a visible label and the combobox element is an HTML element that can be labelled using the HTML label element (e.g., the input element), it is labeled using the label element. Otherwise, if it has a visible label, the combobox element has aria-labelledby set to a value that refers to the labelling element. Otherwise, the combobox element has a label provided by aria-label.

Keyboard accessibility

When focus is in the combo box:

↓ to open the list of options.

When the list is opened:

↑, ↓, Tab or Shift-Tab to navigate between combo boxes.
Enter or Space to select the highlighted option and close the listbox.
Esc to close the list and focus back to the combo box.

Focus indicator

Ensure that the combo box has a visible focus indicator when it is focused.
When the combo box is expanded and users navigate through the options using the keyboard, ensure that each option has a visible focus indicator to indicate the currently focused option.
When the combo box loses focus, the dropdown options should be closed.

Last updated 02 October 2024