Combobox
Filterable or server-driven option selection with active-descendant keyboard navigation and Angular Forms support.
- Selector
- ui-combobox
- Package
- @ngnova/ui/combobox
Import
import { UiComboboxComponent } from '@ngnova/ui/combobox';Usage & variants
Live examples use the public ui-combobox API, paired with the exact snippet a product team would paste into an Angular app.
Framework search
Filterable or server-driven option selection with active-descendant keyboard navigation and Angular Forms support.
Type to filter, then use Arrow keys and Enter.
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use when option sets are large or users benefit from searching before selection.
Watch for
Use unique option values so IDs and tracking remain deterministic.
Product recipes
Apply Combobox in distinct, copyable product scenarios—not just an isolated component state.
Local filtering
Typing clears a stale committed value, filters options, and keeps the listbox keyboard reachable.
1 2 3 4 5 6 7
<ui-combobox
label="Framework"
placeholder="Search frameworks"
[options]="frameworks"
[formControl]="framework"
clearable
/>Server suggestions
Disable local filtering and replace options from a debounced query stream.
1 2 3 4 5 6 7 8
<ui-combobox
label="Repository"
[options]="repositories()"
[loading]="loading()"
[filterOptions]="false"
(queryChange)="searchRepositories($event)"
[formControl]="repository"
/>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
label '' string Visible native label for the text entry control.
placeholder '' string Placeholder shown while the query is empty.
helperText '' string Supporting text described by the input.
errorText '' string Validation message that marks the input invalid.
inputId generated string Stable input ID used by label, listbox, option, and message relationships.
name '' string Native form control name.
ariaLabel '' string Accessible name used when no visible label is supplied.
autocomplete 'off' string Native browser autocomplete token for the query input.
size 'md' 'sm' | 'md' | 'lg' Input frame height, padding, and type scale.
options [] readonly UiComboboxOption[] Available values with labels, optional descriptions, and disabled state.
open false boolean Controlled suggestion-panel state with internal interaction fallback.
disabled false boolean Disables entry, toggle, clearing, and suggestion interaction.
required false boolean Shows the required indicator and exposes aria-required.
clearable false boolean Shows a localized clear action when a query or selection exists.
loading false boolean Shows loading feedback and exposes aria-busy on the listbox.
filterOptions true boolean Filters labels and descriptions locally; disable for parent-owned server results.
openOnFocus true boolean Opens available suggestions when the input receives focus.
noResultsText 'No results found' string Localized empty-result status.
loadingText 'Loading suggestions' string Localized loading status.
clearAriaLabel 'Clear selection' string Localized accessible name for the clear action.
openAriaLabel 'Open suggestions' string Localized accessible name for the closed toggle.
closeAriaLabel 'Close suggestions' string Localized accessible name for the open toggle.
| Name | Type | Default | Description |
|---|---|---|---|
label | string | '' | Visible native label for the text entry control. |
placeholder | string | '' | Placeholder shown while the query is empty. |
helperText | string | '' | Supporting text described by the input. |
errorText | string | '' | Validation message that marks the input invalid. |
inputId | string | generated | Stable input ID used by label, listbox, option, and message relationships. |
name | string | '' | Native form control name. |
ariaLabel | string | '' | Accessible name used when no visible label is supplied. |
autocomplete | string | 'off' | Native browser autocomplete token for the query input. |
size | 'sm' | 'md' | 'lg' | 'md' | Input frame height, padding, and type scale. |
options | readonly UiComboboxOption[] | [] | Available values with labels, optional descriptions, and disabled state. |
open | boolean | false | Controlled suggestion-panel state with internal interaction fallback. |
disabled | boolean | false | Disables entry, toggle, clearing, and suggestion interaction. |
required | boolean | false | Shows the required indicator and exposes aria-required. |
clearable | boolean | false | Shows a localized clear action when a query or selection exists. |
loading | boolean | false | Shows loading feedback and exposes aria-busy on the listbox. |
filterOptions | boolean | true | Filters labels and descriptions locally; disable for parent-owned server results. |
openOnFocus | boolean | true | Opens available suggestions when the input receives focus. |
noResultsText | string | 'No results found' | Localized empty-result status. |
loadingText | string | 'Loading suggestions' | Localized loading status. |
clearAriaLabel | string | 'Clear selection' | Localized accessible name for the clear action. |
openAriaLabel | string | 'Open suggestions' | Localized accessible name for the closed toggle. |
closeAriaLabel | string | 'Close suggestions' | Localized accessible name for the open toggle. |
Outputs
valueChange OutputEmitterRef<string> Emits a committed option value or an empty value when cleared.
queryChange OutputEmitterRef<string> Emits visible query text for analytics or server-side suggestion loading.
openChange OutputEmitterRef<boolean> Emits interaction-requested panel state.
optionSelected OutputEmitterRef<UiComboboxSelection> Emits the selected option and its original source index.
focused OutputEmitterRef<FocusEvent> Emits native input focus without colliding with the DOM focus event name.
blurred OutputEmitterRef<FocusEvent> Emits native input blur after marking the form control touched.
| Name | Type | Description |
|---|---|---|
valueChange | OutputEmitterRef<string> | Emits a committed option value or an empty value when cleared. |
queryChange | OutputEmitterRef<string> | Emits visible query text for analytics or server-side suggestion loading. |
openChange | OutputEmitterRef<boolean> | Emits interaction-requested panel state. |
optionSelected | OutputEmitterRef<UiComboboxSelection> | Emits the selected option and its original source index. |
focused | OutputEmitterRef<FocusEvent> | Emits native input focus without colliding with the DOM focus event name. |
blurred | OutputEmitterRef<FocusEvent> | Emits native input blur after marking the form control touched. |
Accessibility
- The text input uses role="combobox", aria-expanded, aria-controls, aria-autocomplete, and aria-activedescendant while options remain in a named listbox.
- Disabled options expose both native disabled and aria-disabled state, selected options expose aria-selected, and loading exposes aria-busy.
- Visible or aria-only labels, helper/error descriptions, required state, and every utility action are independently localizable.
Keyboard behavior
- Arrow Down and Arrow Up open and cycle enabled suggestions; Home and End move to boundaries.
- Enter commits the active option, Escape closes and restores committed display text, and Tab closes without trapping focus.
- DOM focus remains on the input throughout option navigation.
Testing guidance
- Use UiComboboxHarness to query, open/close, read and select suggestions, inspect active state, clear, and assert disabled or message state.
- Test filtering, async results, disabled options, keyboard wrapping, Escape, blur/touched, clearing, empty/loading states, localization, and Angular Forms.