Autocomplete

Demo & usage

More examples

<sv-autocomplete
  [options]="results"
  [clearable]="true"
  [loading]="isFetching"
  placeholder="Search users…"
  (inputChange)="fetch($event)"
  [(ngModel)]="user" />

<sv-autocomplete [options]="options" [grouped]="true" [(value)]="value" />

When to use

• Typing to filter and pick a single value from a large or remote dataset.
• You want query highlighting, grouping and async-friendly inputChange.
• For multiple selections use Tag Input; for a fixed short list use Select Dropdown.

Async states

• loading
• error
• retry
• partial

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

<sv-autocomplete
  [serverSide]="true"
  [options]="data.items()"
  [loading]="data.loading()"
  [error]="data.error()"
  [totalCount]="data.total()"
  (retry)="data.reload()"
/>

// This component reports its state but does not emit a query, so drive
// it from your own fetch and bind the three async inputs.
readonly items = signal<Row[]>([]);
readonly loading = signal(false);
readonly error = signal<SvDataError | null>(null);

async load(): Promise<void> {
  this.loading.set(true);
  this.error.set(null);
  try {
    this.items.set(await this.api.fetchRows());
  } catch (e) {
    this.error.set(toSvDataError(e));
  } finally {
    this.loading.set(false);
  }
}

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `options`, `loading` and `error`.
• `serverSide` switches **off** the built-in filtering, sorting and paging. Leave it false and the component works entirely from the array you pass — which is what you want for a few hundred rows.
• `debounceMs` (default 300) collapses a burst of typing into one request. Set it to 0 only when the query is driven by clicks.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• `maxItems` (default 8) is a hard boundary, and it used to be a silent one: a query matching 500 options showed eight, offered eight to the keyboard and said nothing about the other 492 — so a user whose entry was 300th concluded it was not there. The panel now discloses it (“Showing 8 of 500 — keep typing to narrow”) as a `role="presentation"` footer row plus a `role="status"` announcement outside the listbox. ⚠️ Deliberately NOT `aria-setsize`: the unrendered options are genuinely unreachable, so declaring 500 would promise items no key can get to — worse than saying nothing.
• With `serverSide`, pass `totalCount` so the disclosure reads “8 of 4,312” rather than counting the one page you handed over; the “keep typing” advice is dropped there, because what a narrower query returns is the host’s endpoint to promise, not this component’s.
• Options with sublabels, icons and disabled state; query highlighting and a configurable no-results message.
• Set `grouped` to render results in labelled sections by each option's `group` (keyboard nav and active-descendant stay correct across sections).
• Clearable, loading state, `maxItems` cap and three sizes; named via `label`.
• Two-way bind `[(value)]` or a reactive control (CVA); listen to `selected`, `cleared`, `inputChange`.

Best practices

• Do: Show a `loading` state and a clear no-results message for async sources.
• Do: Debounce `inputChange` before hitting the server.
• Tip: Make the field `clearable` so users can reset the selection easily.

Accessibility

• Proper ARIA combobox on the `<input>`: `aria-expanded`, `aria-controls` and `aria-activedescendant` track the highlighted option (options carry per-instance ids).
• Arrow keys move, Home/End jump, Enter selects, Esc closes; the input is named by `label` or `placeholder`.
• Implements ControlValueAccessor — works with `[(ngModel)]`, `[formControl]` and `formControlName`.