Attach combobox navigation behavior to an input.

Downloads in past


2.1.72 months ago4 years agoMinified + gzip package size for @github/combobox-nav in KB


Combobox Navigation
Attach combobox navigation behavior (ARIA 1.2) to <input>.


$ npm install @github/combobox-nav



  <input id="robot-input" type="text" />
<ul role="listbox" id="list-id" hidden>
  <li id="baymax" role="option">Baymax</li>
  <!-- `role=option` needs to be present for item to be selectable -->
  <li id="hubot" role="option">Hubot</li>
  <li id="r2-d2" role="option">R2-D2</li>

Markup requirements:
  • Each option needs to have role="option" and a unique id
  • The list should have role="listbox"


import Combobox from '@github/combobox-nav'
const input = document.querySelector('#robot-input')
const list = document.querySelector('#list-id')

// install combobox pattern on a given input and listbox
const combobox = new Combobox(input, list)
// when options appear, start intercepting keyboard events for navigation
// when options disappear, stop intercepting keyboard events for navigation

// move selection to the nth+1 item in the list
// reset selection
// uninstall combobox pattern from the input


A bubbling combobox-commit event is fired on the list element when an option is selected via keyboard or click.
For example, autocomplete when an option is selected:
list.addEventListener('combobox-commit', function (event) {
  console.log('Element selected: ', event.target)

Note When using <label> + <input> as options, please listen on change instead of combobox-commit.

When a label is clicked on, click event is fired from both <label> and its associated input label.control. Since combobox does not know about the control, combobox-commit cannot be used as an indicator of the item's selection state.


For advanced configuration, the constructor takes an optional third argument. For example:
const combobox = new Combobox(input, list, {tabInsertsSuggestions: true})

These settings are available:
  • tabInsertsSuggestions: boolean = true - Control whether the highlighted suggestion is inserted when Tab is pressed (Enter will always insert a suggestion regardless of this setting). When true, tab-navigation will be hijacked when open (which can have negative impacts on accessibility) but the combobox will more closely imitate a native IDE experience.
  • defaultFirstOption: boolean = false - If no options are selected and the user presses Enter, should the first item be inserted? If enabled, the default option can be selected and styled with [data-combobox-option-default] . This should be styled differently from the aria-selected option.
> Warning Screen readers will not announce that the first item is the default. This should be announced explicitly with the use of aria-live status text.


npm install
npm test