Forms

Combobox

An editable input paired with a filterable listbox.

stableEnhancer: enhanceComboboxBuilt on <input> + <ul role="listbox">hydrateless/combobox.css

An editable input paired with a filterable listbox, following the WAI-ARIA combobox pattern. Before JavaScript runs, the stylesheet reveals the listbox on :focus-within so the options are reachable. The enhancer marks the root data-hl-ready, then adds type-to-filter, keyboard navigation that skips disabled options, aria-activedescendant wiring, and selection.

Combobox

Type to filter, use Up/Down to move (Alt+Down expands without moving), PageUp/PageDown to jump, and Enter to select. Home/End stay with the text caret. Disabled options are skipped.

Live

• Apple
• Banana
• Cherry (out of season)
• Grape

JavaScript

This component ships an optional enhancer. With auto-init it loads automatically; to wire it yourself, import it directly:

import { enhanceCombobox } from '@hydrateless/enhancers/combobox';

const handle = enhanceCombobox(document);
// handle.api  -> imperative controls
// handle.destroy()  -> tear everything down

Props

The framework bindings expose these props (and forward the rest to the root element).

Prop	Type	Default	Description
value	string	Not set	Controlled committed value; pair with `onValueChange` (Vue: `v-model`, Svelte: `bind:value`).
defaultValue	string	Not set	Uncontrolled initial value; pre-fills the input.
onValueChange	(value: string) => void	Not set	Called when a selection is committed.
open	boolean	Not set	Controlled listbox visibility; pair with `onOpenChange` (Vue: `v-model:open`, Svelte: `bind:open`).
defaultOpen	boolean	false	Expand the listbox on mount.
onOpenChange	(open: boolean) => void	Not set	Called after the listbox expands or collapses.
filter	boolean	true	Hide options that do not match the typed query.
autoHighlight	boolean	true	Highlight the first match automatically while typing.
ComboboxOption.disabled	boolean	false	Renders `aria-disabled="true"`; the option is skipped and cannot be selected.

Events and callbacks

Event / Callback	Payload	Description
hl:select	{ value: string, option: HTMLElement }	Cancelable CustomEvent on selection; call `preventDefault()` to keep the input unchanged.
hl:change	{ value: string }	Fires after the value commits (also the `onValueChange` callback).
hl:open-change	{ open: boolean }	Fires when the listbox expands or collapses (also the `onOpenChange` callback).

CSS variables

Override these on any ancestor to theme the component. See the theme studio to preview changes live.

CSS variable	Used for
--hl-overlay	Listbox background.
--hl-border	Listbox and input border.
--hl-primary-subtle	Active option highlight.
--hl-focus-shadow	Focus ring on the input.

Accessibility

• The input becomes role="combobox" with aria-expanded, aria-controls, aria-haspopup="listbox", and aria-activedescendant.
• The active option is tracked with aria-selected; Esc, Tab, or an outside click closes the list.
• Options with aria-disabled="true" are skipped during navigation and cannot be committed.

Related

SelectA native select with a CSS-drawn caret.Command PaletteA filterable list of commands with keyboard navigation.Dropdown MenuA button-triggered menu following the WAI-ARIA menu button pattern.