u-elements

<u-combobox> ​

<u-combobox> extends <datalist> with support for multiselect, separate label and programmatic value and clear button. While these features are not yet part of any official ARIA pattern or HTML element, <u-combobox> adhere closely to HTML conventions.

BETA

u-combobox is work in progress. Changes might apply and documentation is not complete.

Quick intro:

  • Use <data> as direct child elements - these are the removable items
  • Use <input> and <u-datalist> to allow adding and suggesting items
  • Use <del> between input and datalist to create a clear button
  • Use data-multiple oto allow selecting multiple items
  • Use data-creatable to allow creating items not in the list
  • Use data-* attributes to translate screen reader announcements
  • Use beforechange, afterchange and beforematch events to manipulate state
  • Add <select> as child for FormData or form submittion compatibility
  • Use matching id on <input> and for attribute on <label> to connect
  • MDN Web Docs: <data> (HTMLDataElement) / <input> (HTMLInputElement) / <datalist> (HTMLDatalistElement) / <option> (HTMLOptionElement)

Example ​

Install ​

bash
npm add -S @u-elements/u-combobox
bash
pnpm add -S @u-elements/u-combobox
bash
yarn add @u-elements/u-combobox
bash
bun add -S @u-elements/u-combobox
html
<script type="module" src="https://unpkg.com/@u-elements/u-combobox@latest/dist/u-combobox.js"></script>

Attributes and props ​

<u-combobox> ​

  • Attributes: all global HTML attributes such as id, class, data-
    • data-sr-added prefixes announcements about additions. Defaults to "Added"
    • data-sr-removed prefixes announcements about removals. Defaults to "Removed"
    • data-sr-remove announces ability to remove. Defaults to "Press to remove"
    • data-sr-empty announces no selected items. Defaults to "No selected"
    • data-sr-found announces where to find amount of selected items. Defaults to "Navigate left to find %d selected"
    • data-sr-invalid announces if trying to select invalid value. Defaults to "Invalid value""
    • data-sr-of separates "number of total" in announcements. Defaults to "of"
  • DOM interface: UHTMLComboboxElement extends HTMLElement
    • UHTMLComboboxElement.control returns HTMLInputElement | null
    • UHTMLComboboxElement.items returns HTMLCollectionOf<HTMLDataElement>
    • UHTMLComboboxElement.list returns HTMLDataListElement | null
    • UHTMLComboboxElement.options returns HTMLCollectionOf<HTMLOptionElement> | undefined
    • UHTMLComboboxElement.values returns string[] with value of each item

<data> ​

  • Attributes: all global HTML attributes such as id, class, data-
    • value optionally specify the machine-readable translation of the text content.
  • DOM interface: HTMLDataElement
    • HTMLDataElement.value string reflecting the value HTML attribute.

Events ​

In addition to the usual events supported by HTML elements, the <u-combobox> elements dispatches custom events allowing you to affect state:

beforechange ​

js
myCombobox.addEventListener('beforechange', (event) => {
  event.target // UHTMLComboboxElement
  event.detail // HTMLDataElement to add or remove
  event.detail.isConnnected // true if removing, false if adding
  event.preventDefault() // Optionally prevent action
})

afterchange ​

js
myCombobox.addEventListener('afterchange', (event) => {
  event.target // UHTMLComboboxElement
  event.detail // HTMLDataElement added or removed
  event.detail.isConnnected // false if removing, true if adding
})

beforematch ​

js
myCombobox.addEventListener('beforematch', (event) => {
  event.target // UHTMLComboboxElement
  event.detail // HTMLOptionElement | undefined match in option list
  // You can change match by looping options and setting option.selected:
  // for (const opt of event.target.options) opt.selected = your-condition-here;
})

Styling ​

<u-combobox> renders as display: block, while <data> renders as display: inline-block with a ::after element to render the removal ×.

Example: Norwegian ​

Example: Custom matching ​

Example: Custom filtering ​

Notice: <u-datalist> has data-nofilter to allow custom filtering

Example: API results ​

Accessibility ​

Screen reader <u-combobox>
VoiceOver (Mac) + Chrome ✅
VoiceOver (Mac) + Edge ✅
VoiceOver (Mac) + Firefox ✅
VoiceOver (Mac) + Safari ✅
VoiceOver (iOS) + Safari ✅
Jaws (PC) + Chrome ✅
Jaws (PC) + Edge ✅
Jaws (PC) + Firefox ✅
NVDA (PC) + Chrome ✅
NVDA (PC) + Edge ✅
NVDA (PC) + Firefox ✅ needs focus mode to announce item removal
Narrator (PC) + Chrome ✅
Narrator (PC) + Edge ✅
Narrator (PC) + Firefox ✅
TalkBack (Android) + Chrome ✅
TalkBack (Android) + Firefox ✅
TalkBack (Android) + Samsung Internet ✅

Specifications ​

Changelog ​

  • 0.0.18: Input value is now reverted instead of cleared when no match on blur/enter
  • 0.0.17: Input now gets new list attribute id of datalist changes
  • 0.0.15: Sync input value when data-elements change and only trigger beforechange and afterchange on click, enter or blur, but not while typing in single mode
  • 0.0.14: Fix issue where removing single element programmatically caused focus
  • 0.0.13: Update sync state when options are changed
  • 0.0.12: Always sync <del> with input value on mount
  • 0.0.11: Improved performance
  • 0.0.10: Only remove <data> during change event for React compatiliby
  • 0.0.9: Improve browser compatibility by avoiding toggleAttribute
  • 0.0.8: Avoid hiding <del> when clicking option without value
  • 0.0.7: Add support for <del> element to clear the input
  • 0.0.6: Ensure correct value of hidden <select>
  • 0.0.5: Prevent input value change when beforechange is prevented
  • 0.0.4: Bugfix
  • 0.0.3: Prevent add if u-option has empty value attribute
  • 0.0.2: Reset value when clicking option in multiple mode
  • 0.0.1: Support async u-option initialization
  • 0.0.0: Beta release

Released under the MIT License