Attach combobox navigation behavior to or .</p> </div> </div> </div> </div> <div class="py-3 border-bottom border-light-dark"> <div class="container"> <ul class="d-flex list-unstyled p-0 position-relative mb-0 mx-n2"> <li class="px-2"> <a class="fw-bold text-primary" href="https://www.opensourceagenda.com/projects/combobox-nav">Overview</a> </li> <li class="px-2"> <a class="fw-bold text-black" href="https://www.opensourceagenda.com/projects/combobox-nav/versions">Versions</a> </li> <li class="px-2"> <a class="fw-bold text-black" href="https://www.opensourceagenda.com/projects/combobox-nav/reviews">Reviews</a> </li> <li class="px-2"> <a class="fw-bold text-black" href="https://www.opensourceagenda.com/projects/combobox-nav/resources">Resources</a> </li> </ul> </div> </div> <div class="container my-5"> <div class="row g-4"> <div class="col-12 col-lg-8 order-2 order-lg-1"> <div> <div class="px-2 mb-3 bg-primary text-white d-inline-block position-relative">Project README</div> <div id="readme" class="section-l" data-base="https://github.com/github/combobox-nav/blob/main/" class="readme mb-4"> <div> <h1>Combobox Navigation</h1> <p>Attach <a href="https://www.w3.org/TR/wai-aria-1.2/#combobox">combobox navigation behavior (ARIA 1.2)</a> to <code><input></code>.</p> <a href="#installation"></a><h2 id="installation">Installation</h2> <pre><code>$ npm install @github/combobox-nav </code></pre> <a href="#usage"></a><h2 id="usage">Usage</h2> <a href="#html"></a><h3 id="html">HTML</h3> <pre><code class="language-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> </code></pre> <p>Markup requirements:</p> <ul> <li>Each option needs to have <code>role="option"</code> and a unique <code>id</code> </li> <li>The list should have <code>role="listbox"</code> </li> </ul> <a href="#js"></a><h3 id="js">JS</h3> <pre><code class="language-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() </code></pre> <a href="#events"></a><h2 id="events">Events</h2> <p>A bubbling <code>combobox-commit</code> event is fired on the list element when an option is selected via keyboard or click.</p> <p>For example, autocomplete when an option is selected:</p> <pre><code class="language-js">list.addEventListener('combobox-commit', function (event) { console.log('Element selected: ', event.target) }) </code></pre> <blockquote> <p><strong>Note</strong> When using <code><label></code> + <code><input></code> as options, please listen on <code>change</code> instead of <code>combobox-commit</code>.</p> </blockquote> <p>When a label is clicked on, <code>click</code> event is fired from both <code><label></code> and its associated input <code>label.control</code>. Since combobox does not know about the control, <code>combobox-commit</code> cannot be used as an indicator of the item's selection state.</p> <p>A bubbling <code>combobox-select</code> event is fired on the list element when an option is selected but not yet committed.</p> <p>For example, autocomplete when an option is selected but not yet committed:</p> <pre><code class="language-js">list.addEventListener('combobox-select', function (event) { console.log('Element selected : ', event.target) }) </code></pre> <a href="#settings"></a><h2 id="settings">Settings</h2> <p>For advanced configuration, the constructor takes an optional third argument. For example:</p> <pre><code class="language-js">const combobox = new Combobox(input, list, {tabInsertsSuggestions: true}) </code></pre> <p>These settings are available:</p> <ul> <li> <code>tabInsertsSuggestions: boolean = true</code> - Control whether the highlighted suggestion is inserted when <kbd>Tab</kbd> is pressed (<kbd>Enter</kbd> will always insert a suggestion regardless of this setting). When <code>true</code>, 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.</li> <li> <code>firstOptionSelectionMode: FirstOptionSelectionMode = 'none'</code> - This option dictates the default behaviour when no options have been selected yet and the user presses <kbd>Enter</kbd>. The following values of <code>FirstOptionSelectionMode</code> will do the following: <ul> <li> <code>'none'</code>: Don't auto-select the first option at all.</li> <li> <code>'active'</code>: Place the first option in an 'active' state where it is not selected (is not the <code>aria-activedescendant</code>) but will still be applied if the user presses <code>Enter</code>. 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.</li> </ul> <blockquote> <p><strong>Warning</strong> Screen readers will not announce that the first item is the default. This should be announced explicitly with the use of <code>aria-live</code> status</p> </blockquote> <ul> <li> <code>'selected'</code>: 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.</li> </ul> </li> <li> <code>scrollIntoViewOptions?: boolean | ScrollIntoViewOptions = undefined</code> - When controlling the element marked <code>[aria-selected="true"]</code> with keyboard navigation, the selected element will be scrolled into the viewport by a call to <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView">Element.scrollIntoView</a>. Configure this value to control the scrolling behavior (either with a <code>boolean</code> or a <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#sect1">ScrollIntoViewOptions</a> object.</li> </ul> <a href="#development"></a><h2 id="development">Development</h2> <pre><code>npm install npm test </code></pre> </div> </div> <div class="text-xs">Open Source Agenda is not affiliated with "Combobox Nav" Project. README Source: <a href="https://github.com/github/combobox-nav" target="_blank">github/combobox-nav</a></div> </div> </div> <div class="col-12 col-lg-4 order-1 order-lg-2"> <div> <div class="d-flex justify-content-center mb-5"> </div> <div class="mb-3"> <div class="row pb-3"> <div class="col-6"> <span class="fw-bold">Stars</span> </div> <div class="col-6 text-end"> <span class="fw-bold">93</span> </div> </div> <div class="row pb-3"> <div class="col-6"> <span class="fw-bold">Open Issues</span> </div> <div class="col-6 text-end"> <span class="fw-bold">5</span> </div> </div> <div class="row pb-3"> <div class="col-6"> <span class="fw-bold">Last Commit</span> </div> <div class="col-6 text-end"> <span class="fw-bold">1 month ago</span> </div> </div> <div class="row pb-3"> <div class="col-12"> <span class="fw-bold">Repository</span> </div> <div class="col-12"> <a href="https://github.com/github/combobox-nav" target="_blank" class="fw-bold text-primary">github/combobox-nav</a> </div> </div> <div class="row pb-3"> <div class="col-6"> <span class="fw-bold">License</span> </div> <div class="col-6 text-end"> <a href="https://www.opensourceagenda.com/tags/mit" class="font-bold text-primary">MIT</a> </div> </div> <div class="row pb-3"> <div class="col-12"> <span class="fw-bold">Homepage</span> </div> <div class="col-12"> <a href="https://github.github.io/combobox-nav/examples/index.html" class="text-primary fw-bold">https://github.github.io/combobox-nav/examples/index.html</a> </div> </div> <div class="row pb-3"> <div class="col-12"> <span class="fw-bold">Tags</span> </div> <div class="col-12"> <a href="https://www.opensourceagenda.com/tags/autocomplete" class="fw-bold text-primary me-3">Autocomplete</a> <a href="https://www.opensourceagenda.com/tags/combobox" class="fw-bold text-primary me-3">Combobox</a> <a href="https://www.opensourceagenda.com/tags/decorator" class="fw-bold text-primary me-3">Decorator</a> </div> </div> </div> <div class="mb-4"> <div class="card bg-light p-3"> <h4>Open Source Agenda Badge</h4> <div class="mb-3"> <img src="https://www.opensourceagenda.com/projects/combobox-nav/reviews/badge.svg" alt="Open Source Agenda Rating" /> </div> <div> <textarea class="w-100 p-2 border-white bg-light text-dark" readonly style="height:115px;word-break:break-all;"><a href="https://www.opensourceagenda.com/projects/combobox-nav"><img src="https://www.opensourceagenda.com/projects/combobox-nav/reviews/badge.svg" alt="Open Source Agenda"></a>
