@github/combobox-nav

中文文档
3.0.2发布于 2026/07/01MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 29.8万

Attach combobox navigation behavior to an input.

原始使用文档
文档目录7 节
  1. Installation
  2. Usage
  3. HTML
  4. JS
  5. Events
  6. Settings
  7. Development

Combobox Navigation

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

Installation

$ npm install @github/combobox-nav

Usage

HTML

<label>
  Robot
  <input id="robot-input" type="text" />
</label>
<ul role="listbox" id="list-id" hidden>
  <li id="baymax" role="option">Baymax</li>
  <li><del>BB-8</del></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>
</ul>

Markup requirements:

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

JS

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
combobox.start()
// when options disappear, stop intercepting keyboard events for navigation
combobox.stop()

// move selection to the nth+1 item in the list
combobox.navigate(1)
// reset selection
combobox.clearSelection()
// uninstall combobox pattern from the input
combobox.destroy()

Events

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.

A bubbling combobox-select event is fired on the list element when an option is selected but not yet committed.

For example, autocomplete when an option is selected but not yet committed:

list.addEventListener('combobox-select', function (event) {
  console.log('Element selected : ', event.target)
})

Settings

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.
  • firstOptionSelectionMode: FirstOptionSelectionMode = 'none' - This option dictates the default behaviour when no options have been selected yet and the user presses Enter. The following values of FirstOptionSelectionMode will do the following:
    • 'none': Don't auto-select the first option at all.
    • 'active': Place the first option in an 'active' state where it is not selected (is not the aria-activedescendant) but will still be applied if the user presses Enter. To select the second item, the user would need to press the down arrow twice. This approach allows quick application of selections without disrupting screen reader users.

    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

    • 'selected': Select the first item by navigating to it. This allows quick application of selections and makes it faster to select the second item, but can be disruptive or confusing for screen reader users.
  • scrollIntoViewOptions?: boolean | ScrollIntoViewOptions = undefined - When controlling the element marked [aria-selected="true"] with keyboard navigation, the selected element will be scrolled into the viewport by a call to Element.scrollIntoView. Configure this value to control the scrolling behavior (either with a boolean or a ScrollIntoViewOptions object.

Development

npm install
npm test

版本与发布记录

@github/combobox-nav 共发布 25 个版本,首次发布于 2018/11/08;过去 12 个月发布了 1 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.0.2latest2026/07/014 个月前
3.0.12024/02/272 年前
3.0.02024/02/232 年前
2.3.12023/12/242 年前
2.3.02023/09/253 年前
2.2.02023/09/153 年前

关于 @github/combobox-nav 的常见问题

@github/combobox-nav 是什么?

Attach combobox navigation behavior to an input.

如何安装 @github/combobox-nav?

在项目目录运行 npm install @github/combobox-nav,或使用 pnpm add / yarn add / bun add。

@github/combobox-nav 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@github/combobox-nav 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@github/combobox-nav 可以商用吗?

@github/combobox-nav 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@github/combobox-nav 的下载量有多少?

根据 npm 官方下载统计,@github/combobox-nav 在 2026/10/17 – 2026/11/15 这 30 天内被下载 297,724 次,日均约 9,924 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@github/combobox-nav 还在维护吗?

最新版本 3.0.2 发布于 2026/07/01(4 个月前);至今共发布 25 个版本,其中过去 12 个月发布了 1 个;首次发布于 2018/11/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。