Combobox

Problem Context

• The product needs one submitted value, often with both a human-readable label and an internal option ID.
• The option set is too long, dynamic, or filtered to work well as radio buttons or a simple select.
• Users may know part of the value and need typing to narrow options.
• Opening the popup, navigating options, accepting a value, and cancelling exploration have different meanings.
• The typed string may be different from the last committed option and must not submit a stale selected ID.

Selection Rules

• Choose a combobox when a single field controls a popup of allowed or suggested values.
• Use it when users need to type to filter, open the popup to browse, or copy and edit the displayed value.
• Use autocomplete as the behavior inside a combobox when suggestions complete what the user typed.
• Use native select when the choices are few enough to browse directly and typing is unnecessary.
• Use text input when any arbitrary value is valid and there is no popup or selected option to maintain.
• Use multi-select or chip selection when users need more than one committed value.
• Use typeahead or search suggestions when the interaction is open-ended discovery or query formulation rather than choosing one field value.
• Allow custom values only when the domain accepts values outside the list, and show that policy before validation.

Required States

• Collapsed empty state with label, help text, and popup affordance.
• Focused collapsed state with current value and selected option status.
• Expanded popup state with controlled listbox, grid, tree, or dialog.
• Filtered option state after typing.
• Active descendant state distinct from committed selection.
• Accepted option state with visible label and synchronized submitted ID.
• Edited-after-selection state where the selected ID is cleared or marked unresolved.
• No matching option state.
• Custom value allowed state.
• Custom value disallowed validation state.
• Escape-cancelled state that preserves the previous accepted value.
• Disabled and read-only states with readable value.

Interaction Contract

• The combobox element owns or controls its popup with aria-controls when the popup is available.
• aria-expanded reflects whether the popup is visible.
• For listbox, grid, or tree popups, DOM focus remains on the combobox while aria-activedescendant identifies the active option.
• Arrow keys move the active option without breaking normal text editing.
• Enter or pointer selection accepts the active option, updates the visible value, and synchronizes the submitted option ID.
• Escape closes the popup without committing an explored option unless the product has a documented clearing behavior.
• Typing after a committed selection clears or invalidates the selected ID until a new valid option or accepted custom value is chosen.
• Validation distinguishes unresolved typed text from an accepted option and announces any required repair.

Implementation Checklist

• Decide whether the combobox is editable or select-only, whether values are restricted to the list, and whether custom values are permitted.
• Define the popup role, option identity, selected-value model, filtering behavior, no-result behavior, and stale-response handling before wiring the component.
• Use a native select when it satisfies the job; build a custom combobox only when popup ownership, filtering, or active option behavior is required.
• Give the field a visible label and ensure its accessible name is distinct from the current value.
• Set aria-expanded, aria-controls, aria-autocomplete when appropriate, and aria-activedescendant for active options in listbox, grid, or tree popups.
• Keep focus management compatible with standard single-line text editing keys and do not capture keys needed for cursor movement, selection, copy, paste, undo, or deletion.
• Clear stale selected IDs whenever typed text diverges from the accepted option unless custom text is explicitly accepted.
• Test pointer, keyboard, screen reader, touch, high zoom, forced colors, slow filtering, no results, invalid text, Escape, Enter, disabled, read-only, and form submission.

Common Generated-UI Mistakes

• Using a custom combobox for a short list where native select, radio buttons, or segmented controls would be simpler.
• Treating highlighted, active, and selected states as the same thing.
• Submitting the last selected option ID after the user changes the visible text.
• Moving DOM focus into popup options for an editable combobox and breaking text editing.
• Forcing the first result before the user accepts it.
• Leaving aria-expanded, aria-controls, or aria-activedescendant stale when the popup opens, closes, or filters.
• Allowing arbitrary custom values in a domain that requires a known record.

Critique Questions

• Does this field need a popup-owning widget, or is the real need autocomplete behavior, select, text input, or multi-select?
• Can users tell the difference between typed text, active option, and committed selected value?
• What happens to the submitted ID when the user edits the visible value after selecting an option?
• Can keyboard users open, move, accept, cancel, clear, and submit without losing text editing behavior?
• Are custom values allowed, rejected, or accepted only after an explicit action?