Start typing, then choose from the list
Default
The label and an empty field, with a caret to show it opens.
Lets people pick one answer from a long list by typing to filter it, like an LGA, a country or a ministry.
Updated
Select an LGA from the list
Combo box
<div class="nds-combo-box nds-combo-box--error"> <div class="nds-combo-box__label-row"> <label class="nds-combo-box__label" for="docs-combo-live"> Local government area </label> <span class="nds-combo-box__required" aria-hidden="true"> * </span> </div> <div class="nds-combo-box__control-wrap"> <input class="nds-combo-box__control" id="docs-combo-live" type="text" role="combobox" autocomplete="off" aria-autocomplete="list" aria-expanded="false" aria-controls="docs-combo-live-listbox" aria-describedby="docs-combo-live-error" aria-invalid="true" value="Ikeja" /> <span class="nds-combo-box__icon" aria-hidden="true"> <svg class="nds-combo-box__icon-svg" focusable="false" aria-hidden="true"> <use href="#nds-icon-caret"> </use> </svg> </span> </div> <div class="nds-select__menu" hidden> <ul class="nds-select__menu-list" id="docs-combo-live-listbox" role="listbox" aria-label="Local government area"> </ul> </div> <p class="nds-combo-box__error" id="docs-combo-live-error" role="alert"> <svg class="nds-combo-box__error-icon" width="16" height="16" focusable="false" aria-hidden="true"> <use href="#nds-icon-error"> </use> </svg> <span> Select an LGA from the list </span> </p></div> A combo box is a text field with a list underneath. As people type, the list shrinks to the matches. Only answers from the list are accepted.
What people see as they type. The list opens under the field and shows up to 6 matches before it scrolls.
Start typing, then choose from the list
The label and an empty field, with a caret to show it opens.
Matches show as people type. The option the keyboard is on has a 2px border.
Says nothing matched and how to recover.
Select an LGA from the list
Says what to fix, with a red border. What people typed stays.
The properties of Form/Combo box. The same in HTML, WordPress and React.
| Property | Type | Possible values | Description |
|---|---|---|---|
| state | string |
| Open shows the list. It scrolls after 6 options, with a visible scrollbar. |
| error | boolean |
| Shows the error message and a red border. |
| options | array |
| The full list. Only these values are accepted. |
In code, follow the WAI-ARIA combobox pattern: <input role="combobox" aria-expanded aria-controls aria-autocomplete="list"> and a <ul role="listbox">. Announce the number of matches with aria-live="polite".
| Part | Token | Contrast on the page |
|---|---|---|
| Border | border/strong, 1px | 4.2:1 |
| Border when focused | border/dark, 2px | 14.3:1 |
| Border in an error | status/error/surface, 1px (2px when focused) | 4.9:1 |
| Menu | surface/container, border/default 1px, radius/050 · below the field | Exempt |
| Option the keyboard is on | border/dark, 2px | 14.3:1 |
| Option height | spacing/500 (40px) | — |
Filter as people type, and keep the matches in the same order as the full list.
Don’t use a combo box for a short list. If there are 15 options or fewer, use a select.
How the field and its list sit on a form.
How to write the label, hint and messages.
“Local government area (LGA)”, not just “LGA”.
A hint like “Start typing, then choose from the list”.
“No LGA matches ‘lkj’. Check the spelling.”
| Write | Don’t write | Why |
|---|---|---|
| Local government area (LGA) | Select LGA | Says what to enter, in full. |
| Start typing, then choose from the list | Type to search | Says what happens next. |
| No LGA matches ‘lkj’. Check the spelling. | No results | Says how to recover. |
Follows the WAI-ARIA combobox pattern, so screen readers announce the field, the list and how many matches there are.
| Key | What it does |
|---|---|
| ↓ ↑ | Moves through the options. |
| Enter | Chooses the option the keyboard is on. |
| Esc | Closes the list and keeps what was typed. |
| Tab | Closes the list and moves on. |
Copy the code for HTML, WordPress or React from the Code tab in Live example. The options are listed under Specifications.
Use Combo box from the NDS Website documentation frames. Match node 900:179898 for states, tokens and copy.
Is this page useful?