HyCombobox

A combobox — a filterable single-select that combines a text input with a listbox popup. Follows the WAI-ARIA APG combobox pattern: DOM focus stays on the input, option highlight moves via aria-activedescendant.

The listbox is positioned with Floating UI: offset + flip + shift keep the popup inside the viewport near the input, and the size middleware caps the listbox height to the available space so long lists remain scrollable instead of spilling off-screen. autoUpdate repositions on scroll/resize while the listbox is open.

Alpha scope: single-select, client-side filtering, no creatable free text, no virtualization. Multi-select ships as a sibling hy-multi-combobox; creatable values are deferred.

Options are passed as a property (.options = [...]). The value property is the currently committed option value (or null). Filtering is controlled internally via filterOption; return false for every option to disable client filtering and drive options server-side.

Accessible name. Provide one of: the label property (visible label above the control), aria-label on the host (when the surrounding context already names it), or aria-labelledby referencing another element's id. The dev-mode WCAG 1.3.1 warning fires only when none of the three is set; aria-label / aria-labelledby on the host are forwarded to the inner <input> so screen readers see them.

Examples

<hy-combobox label="Country" placeholder="Search countries"></hy-combobox>
<script>
  const box = document.querySelector('hy-combobox');
  box.options = [
    { value: 'ch', label: 'Switzerland' },
    { value: 'fr', label: 'France' },
    { value: 'de', label: 'Germany' },
  ];
  box.addEventListener('change', (e) => console.log(e.detail.value));
</script>

Events

• change - Fires when the selected value commits. Detail: ComboboxChangeDetail.
• input - Fires while the user types. Detail: ComboboxInputDetail.
• show - Fires when the listbox opens (does NOT bubble). Detail: HyVisibilityDetail.
• hide - Fires when the listbox closes (does NOT bubble). Detail: HyVisibilityDetail.

Methods

select()

Selects all text in the combobox's underlying input.