Component v1.1.0 Forms

Combobox

Filterable or server-driven option selection with active-descendant keyboard navigation and Angular Forms support.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-combobox
Package
@ngnova/ui/combobox

Import

Standalone Tailwind v4
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.

API Reference

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.

Angular template ui-combobox-recipe.example.html
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.

Angular template ui-combobox-recipe.example.html
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.

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.

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.