API Reference — Angular — AI Autocomplete Docs

Every input, output, observable, and method — distilled.

<ai-autocomplete>

The full drop-in standalone component. Owns the contentEditable editor, inline pills, dropdown, and all state. Implements ControlValueAccessor for Reactive Forms.

Inputs

Prop	Type	Default	Description
`apiConfig`	`APIConfig`	—	Runtime API configuration (public key or access token).
`pillPlacement`	`"inline" \| "dropdown" \| "hidden"`	`"inline"`	Where unfilled pills render. inline lives in the input; dropdown places them with the options; hidden shows none.
`mode`	`"light" \| "dark" \| "auto"`	`"auto"`	Color mode. auto follows prefers-color-scheme.
`optionsPosition`	`"above" \| "below"`	`"below"`	Where the dropdown opens relative to the input.
`animations`	`boolean`	`true`	Enable the selection streak + new-param shimmer.
`dropdownTrigger`	`"auto" \| "manual" \| "hidden"`	`"auto"`	When the dropdown appears. auto = when options are available; manual = only on pill tap; hidden = never.
`closeDropdownOnBlur`	`boolean`	`true`	When false, the dropdown stays open even when the editor loses focus.
`showNonTappableOptions`	`boolean`	`true`	Render non-tappable options alongside tappable ones.
`columns`	`number`	`2`	Number of columns in the dropdown grid.
`maskCompletedText`	`boolean`	`false`	Strip completed-param text from network requests (PII masking).
`optionOverrides`	`OptionOverrides`	—	Inject or compute option lists per suggestion type.
`autoFocus`	`boolean`	`true`	Focus the editor on mount. Set false to leave focus to the consumer.
`value`	`string`	—	Controlled text value. Pair with (valueChange).
`completedParams`	`CompletedParamState[]`	—	Controlled completed params. Pair with (completedParamsChange).
`submitButton`	`TemplateRef \| null`	—	A <ng-template> to replace the default arrow button. Pass null to render no button.

Outputs

Prop	Type	Default	Description
`submitted`	`EventEmitter<AutocompleteResult>`	—	Emits on Enter or submit-button click. Carries an AutocompleteResult.
`errored`	`EventEmitter<Error>`	—	Emits when a fetch fails.
`valueChange`	`EventEmitter<string>`	—	Emits when text changes (controlled mode).
`completedParamsChange`	`EventEmitter<CompletedParamState[]>`	—	Emits when completed params change (controlled mode).
`focused`	`EventEmitter<void>`	—	Emits when the editor gains focus.
`blurred`	`EventEmitter<void>`	—	Emits when the editor loses focus.

Imperative methods

Call these on the component instance via a template reference variable + @ViewChild.

Prop	Type	Default	Description
`focus()`	`() => void`	—	Focus the editor.
`blur()`	`() => void`	—	Blur the editor.
`reset()`	`() => void`	—	Clear all state, rotate the session, and re-fetch.
`setMode()`	`(mode: AppearanceMode) => void`	—	Switch color mode at runtime.

AIAutocompleteController

A plain TypeScript class — no DI. Create it with new in ngOnInit, hold the reference, and call destroy() in ngOnDestroy. Exposes the SDK's reactive state as RxJS observables plus action methods.

Constructor options

Pass these to the constructor. Event callbacks (onSubmit, onError, …) are registered once at construction — for dynamic reactivity, subscribe to the observables instead.

Prop	Type	Default	Description
`apiConfig`	`APIConfig`	—	Runtime API configuration (key or token).
`optionsPosition`	`"above" \| "below"`	`"below"`	Where the dropdown opens. Read by the keyboard controller to pick the open key.
`dropdownTrigger`	`"auto" \| "manual" \| "hidden"`	`"auto"`	When the dropdown appears.
`closeDropdownOnBlur`	`boolean`	`true`	When false, the dropdown stays open even when the input loses focus.
`showNonTappableOptions`	`boolean`	`true`	Render non-tappable options alongside tappable ones.
`columns`	`number`	`2`	Number of columns in the dropdown grid.
`maskCompletedText`	`boolean`	`false`	Strip completed-param text from network requests (PII masking).
`optionOverrides`	`OptionOverrides`	—	Override option lists per suggestion type.
`value`	`string`	—	Initial controlled text value.
`completedParams`	`CompletedParamState[]`	—	Initial controlled completed params.
`onSubmit / onError / onChange`	`(...) => void`	—	onSubmit, onError, onChange, onParamsChange, onFocus, onBlur — registered once at construction.

Observables

Each field is exposed as a stand-alone observable plus a composite state$. All run through distinctUntilChanged + shareReplay, so multiple async pipes share one subscription.

Prop	Type	Default	Description
`state$`	`Observable<AIAutocompleteControllerState>`	—	Snapshot of every public field in one object — convenient for *ngIf="ctrl.state$ \| async as state".
`dropdown$`	`Observable<AIAutocompleteDropdownState>`	—	Composite stream for the dropdown view (suggestions, activeIndex, isOpen, pills, …) — bound to <ai-autocomplete-dropdown> via [controller], or subscribe to it directly to render your own dropdown in Tier 3.
`text$`	`Observable<string>`	—	Current editor text.
`completedParams$`	`Observable<CompletedParamState[]>`	—	Filled parameters.
`suggestionPills$`	`Observable<Suggestion[]>`	—	Actionable suggestion pills. The first item is the active pill.
`segments$`	`Observable<Segment[]>`	—	Input text split into typed text vs completed-param segments.
`isLoading$`	`Observable<boolean>`	—	Whether a fetch is in progress (UI-visible).
`isDropdownOpen$`	`Observable<boolean>`	—	Whether the dropdown should be visible.
`isReady$`	`Observable<boolean>`	—	Server indicates the query is complete.
`error$`	`Observable<Error \| null>`	—	Last fetch error, or null.
`activeIndex$`	`Observable<number>`	—	Highlighted dropdown option index. -1 = none.

Actions

Thin pass-throughs to the headless core. After destroy() they no-op safely.

Prop	Type	Default	Description
`handleTextChange()`	`(value: string) => void`	—	Call when the user types. Handles capitalization, param reconciliation, and filtering.
`handleKeyDown()`	`(e: KeyboardEvent) => void`	—	Forward keyboard events from your input. Handles arrow nav, Enter, Tab, Escape.
`setFocused()`	`(focused: boolean) => void`	—	Notify the controller the input gained or lost focus. Custom inputs only — [aiaInput] does this for you.
`handleCaretMove()`	`(offset: number \| null) => void`	—	Report the caret position (plain-text offset) so arrow keys can move into the dropdown. Custom inputs only.
`selectOption()`	`(option: SuggestionOption) => void`	—	Select a dropdown option — updates text, creates a completed param, triggers shimmer.
`setActiveDropdownIndex()`	`(index: number) => void`	—	Highlight a dropdown option by index (-1 = none). Use it to wire hover/keyboard highlighting when rendering your own dropdown.
`setActivePill()`	`(index: number) => void`	—	Move the pill at index to the front (active).
`removeLastParam()`	`() => void`	—	Remove the last completed param and restore it as a pill.
`setValue()`	`(text: string) => void`	—	Set the editor text (controlled mode).
`setCompletedParams()`	`(params: CompletedParamState[]) => void`	—	Set completed params (controlled mode).
`reset()`	`() => void`	—	Clear all state, rotate the session, and re-fetch. Call after submit.
`update()`	`(opts: AIAutocompleteControllerUpdate) => void`	—	Apply runtime option changes (e.g. dropdownTrigger, optionsPosition). Event callbacks can't be swapped — subscribe to the observables instead.
`getState()`	`() => AIAutocompleteControllerState`	—	Synchronous snapshot of the current state (for use inside event handlers).
`destroy()`	`() => void`	—	Release subscriptions and the underlying core. Call in ngOnDestroy.

<ai-autocomplete-dropdown>

Tier 2 dropdown component. Pass it the same controller — it renders the pillbar, options grid, and loading skeleton, and forwards actions back to the controller.

Prop	Type	Default	Description
`controller`Required	`AIAutocompleteController`	—	The controller that owns the autocomplete state.
`showPills`	`boolean`	`true`	Whether to render the pillbar inside the dropdown.
`mode`	`"light" \| "dark" \| "auto"`	—	Color mode for a standalone dropdown — self-scopes the SDK tokens so no .magicx-aia wrapper is needed. "auto" follows prefers-color-scheme. Leave unset when nested inside a .magicx-aia ancestor (e.g. Tier 1).
`className`	`string`	—	CSS class applied to the dropdown root.

[aiaInput] directive

Attach [aiaInput]="controller" to your own <textarea> or <input> to wire its events (input, keydown, focus, blur, caret moves) into the controller and mirror state into ARIA attributes. Implements ControlValueAccessor, so it also works with [formControl] / [(ngModel)].

AutocompleteResult

The shape emitted by (submitted).

Prop	Type	Default	Description
`query`	`string`	—	Plain text as the user sees it.
`raw_query`	`string`	—	Text with placeholder tokens (e.g. "Create a {{TASK_1}}").
`completed_params`	`CompletedParam[]`	—	Filled parameter values.