Combobox

Use hui-combobox when users need to type a query and choose one or more options from a managed list. Use a select when free-text filtering is not needed. Do not use it as a generic search field without options or as a replacement for a command menu.

• Root: hui-combobox
• Input and trigger: hui-combobox-input, hui-combobox-trigger
• Popup: hui-combobox-content
• Options and feedback: hui-combobox-option, hui-combobox-empty, hui-combobox-status

hui-combobox

The root exposes data-state="open|closed", data-value, data-query, data-results, and data-empty. It emits hui-open-change and hui-value-change events with { open } and { value } details.

Input, trigger, and content

hui-combobox-input renders a native <input> with role="combobox", aria-expanded, aria-controls, aria-autocomplete, aria-haspopup="listbox", aria-activedescendant, and aria-busy. The input owns keyboard handling and retains focus. hui-combobox-trigger renders a labelled button that toggles the popup without stealing input focus.

hui-combobox-content renders role="listbox", inherits accessible naming, and is hidden while closed. Open content is positioned against the input and portalled when a clipped ancestor would contain it. After opening, page scrolling does not reposition the content; it stays at its last document coordinates, allowing the page to carry it out of the viewport. Opening and viewport resizing still run collision-aware positioning. data-state and data-placement are exposed.

For selection="multiple", consumers may project a selected-values surface. A token should expose its committed value through data-value and contain an accessible button[type="button"][data-remove-value]. The remove attribute may contain the value itself; when empty, the nearest token's data-value is used. The component owns the mutation and emits the existing hui-value-change event; consumers own token labels, layout, and rerendering. Remove controls are ignored for single-selection and disabled roots.

Options, empty, and status

• hui-combobox-option renders role="option", aria-selected, aria-disabled, a deterministic ID, and data-highlighted.
• hui-combobox-empty renders an optional role="status" empty-result message.
• hui-combobox-status renders an optional polite status for loading or result metadata; result announcements also use the shared polite live-region helper.
• Set busy while the consumer is fetching or replacing options. The input and listbox expose aria-busy="true", and a projected hui-combobox-status is visible only while the popup is open and busy. The component does not start a request or change popup visibility when busy changes.
• The documentation playground's Show loading results control intentionally opens the popup when enabled so the status can be inspected; this convenience behavior is not part of the component API.
• Options use value, label, disabled, and optional selected attributes. When value is omitted, option identity falls back to the host id, then the option's positional index; use explicit values for collections whose order can change. Their projected text is the fallback accessible label.

• Typing filters options. input events with isComposing do not filter until composition ends. filter="auto" matches prefixes; contains matches any substring; none keeps every option.
• Closed ArrowDown/ArrowUp opens and highlights the selected option, or the first/last enabled result. Open arrows move the highlight, skipping disabled or filtered options; loop wraps at the ends.
• Closed Home/End retain native caret behavior. Open Home/End move the highlight to the first/last enabled result.
• Open Enter commits the highlighted option. Closed Enter remains available for form submission when enter-submit is present.
• Escape is staged: clear a non-selected highlight, then close, then restore the committed label/query. Tab commits the highlighted option when select-on-tab is present and always closes without trapping focus.
• In autocomplete="both", the first prefix match supplies a selected inline completion tail. ArrowRight and Tab accept the completion.
• Pointer activation selects an option. Pointer-down keeps focus on the input. Outside pointer/focus and Escape dismiss the popup.
• Multiple selection toggles options without closing and keeps the input ready for another query.
• When a multiple-selection input is empty, Backspace or Delete removes the last committed value. With a non-empty query, both keys retain native text editing behavior.

SSR renders the editable input, trigger, and a complete collapsed listbox with resolved option selection. It also renders a hidden form value input and a native datalist twin so the input remains useful without JavaScript. default-value, default-query, and default-open are resolved on the server. Closed content has hidden="hidden"; portal markers are client-only.

Hydration re-renders component-owned template nodes while preserving projected consumer content and host attributes. In an enhanced browser the custom listbox owns suggestions and the input's list association is removed, while the datalist node remains available in the DOM. Without JavaScript, the native input and its datalist remain usable; the custom listbox is hidden and the committed value is available through the hidden form input.

<hui-combobox id="plan" name="plan" aria-label="Plan" filter="contains">
  <hui-combobox-input placeholder="Search plans"></hui-combobox-input>
  <hui-combobox-trigger aria-label="Show plans">Options</hui-combobox-trigger>
  <hui-combobox-content>
    <hui-combobox-option value="basic">Basic</hui-combobox-option>
    <hui-combobox-option value="pro">Professional</hui-combobox-option>
    <hui-combobox-empty>No plans found</hui-combobox-empty>
  </hui-combobox-content>
</hui-combobox>

<hui-combobox id="playground-combobox" name="plan" value="standard" aria-label="Plan" filter="contains" autocomplete="both">
  <hui-combobox-input placeholder="Search plans"></hui-combobox-input>
  <hui-combobox-trigger aria-label="Show plans">Options</hui-combobox-trigger>
  <hui-combobox-content>
    <hui-combobox-option value="basic">Basic</hui-combobox-option>
    <hui-combobox-option value="standard">Standard</hui-combobox-option>
    <hui-combobox-option value="pro">Professional</hui-combobox-option>
    <hui-combobox-empty>No plans found.</hui-combobox-empty>
    <hui-combobox-status>Loading plans...</hui-combobox-status>
  </hui-combobox-content>
</hui-combobox>

• SelectChoose one or more values from a known set without free-text editing.
• FieldConnect a control with its label, description, required state, and validation message.
• Dropdown MenuPresent a short command or selection list from a menu button.