HyCombobox

Usage examples on this page are written for Lit / plain HTML (<hy-combobox>). The same component ships as HyCombobox in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

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>

API

Properties

Property	Attribute	Type	Default	Description
options	—	ComboboxOption[]	[]	Option list. Property-only — arrays are not reflectable.
value	value	string | null	null	Committed value. null when nothing is selected.
label	label	string	''	Visible label above the input.
helperText	helper-text	string	''	Helper text below the input. Hidden when errorMessage is shown.
errorMessage	error-message	string	''	Error message — shown below the input when invalid.
placeholder	placeholder	string	''	Placeholder shown when the input is empty.
size	size	'small' | 'medium' | 'large'	'medium'	Input size — matches sibling form controls.
layout	layout	'block' | 'inline'	'block'	Row layout: block (default) stacks label above the combobox; inline puts label on the left and combobox on the right. Helper/error always sit under the control (col 2–end), never under the label. Set --hy-combobox-label-column-width on a wrapping container so stacked comboboxes align.
width	width	string | undefined	—	Width of the combobox container. Accepts any valid CSS width value (e.g. '400px', '100%', '20rem'). The host fills its container by default; set width to constrain the field. Mirrors hy-text-input.
name	name	string	''	Form name — surfaces the selected value to FormData.
disabled	disabled	boolean	false	Disables the control.
required	required	boolean	false	Marks the field as required for form validation.
invalid	invalid	boolean	false	Visually marks the field as invalid.
clearable	clearable	boolean	true	Whether to show a clear-button when a value is set.
clearLabel	clear-label	string	'Clear selection'	Accessible name of the clear button.
emptyText	empty-text	string	'No results'	Fallback text when no options match the current query.
open	open	boolean	false	Controlled open state. Leave unset for uncontrolled behavior.
autofocus	autofocus	boolean	false	Marks this combobox as the auto-focus target. Read by hy-dialog (and other overlay containers) on show to choose initial focus. Also focuses on first connect when used outside an overlay, mirroring native HTML autofocus but routed through JS so SSR'd HTML doesn't pull focus during hydration.
autoselect	autoselect	boolean	false	After auto-focus lands, selects the current value so the user can type-to-replace. Pairs with autofocus for rename-style dialogs where the existing value is shown for context but is meant to be overwritten.
filterOption	—	ComboboxFilter	defaultFilter	Custom filter. Called for each option; return true to include. Default is a case-insensitive substring match on label.
form	—	HTMLFormElement | null	—	—
validity	—	ValidityState	—	—
validationMessage	—	string	—	—

Events

Event	Detail	Description
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.

CSS Parts

Part	Description
base	Outer wrapper containing label, control, helper/error.
label	The <label> element.
container	The input + trailing icons container.
input	The text <input>.
clear-button	The clear affordance (visible when clearable and a value is set).
expand-icon	The chevron indicating popup state.
listbox	The popup <ul role="listbox">.
option	An individual <li role="option">.
empty	The no-results message container.
helper-text	Helper text below the input.
error-message	Error message below the input.

CSS Custom Properties

Property	Description
--hy-combobox-listbox-max-height	Maximum height of the popup before scrolling. Overridden at runtime by Floating UI's size middleware when viewport space is tighter.
--hy-combobox-label-column-width	Width of the label column in layout="inline" mode. No default — set on a wrapping container so stacked comboboxes align.
--hy-combobox-height-sm	Outer height for small size variant. Per-component override in the form-control height contract (see .claude/rules/control-heights.md). Default: var(--hy-control-height-sm)
--hy-combobox-height-md	Outer height for medium size variant. Default: var(--hy-control-height-md)
--hy-combobox-height-lg	Outer height for large size variant. Default: var(--hy-control-height-lg)
--hy-combobox-hover-duration	Transition duration for hover and focus state feedback
--hy-combobox-hover-easing	Transition easing for hover and focus state feedback
--hy-combobox-expand-duration	Transition duration for the listbox expand and collapse animation
--hy-combobox-expand-easing	Transition easing for the listbox expand and collapse animation

Methods

select()

Selects all text in the combobox's underlying input.