API Reference — JavaScript — AI Autocomplete Docs

Every constructor option, instance method, state field, and event — for the framework-agnostic SDK.

Constructor options

Pass these to the constructor as the second argument.

Prop	Type	Default	Description
`renderMode`	`"full" \| "dropdown" \| "headless"`	`"full"`	Tier — full owns everything; dropdown lets you own the input; headless gives you state only.
`apiConfig`Required	`APIConfig`	—	Runtime API configuration (key or token).
`placeholder`	`string`	—	Fallback placeholder when the server doesn't return one.
`columns`	`number`	`2`	Number of columns in the dropdown grid.
`mode`	`"light" \| "dark" \| "auto"`	`"auto"`	Color mode. auto follows prefers-color-scheme.
`optionsPosition`	`"above" \| "below"`	`"below"`	Where the dropdown opens.
`animations`	`boolean`	`true`	Enable selection streak + shimmer animations.
`pillPlacement`	`"inline" \| "dropdown" \| "hidden"`	`"inline"`	Where unfilled pills render.
`dropdownTrigger`	`"auto" \| "manual" \| "hidden"`	`"auto"`	When the dropdown appears.
`closeDropdownOnBlur`	`boolean`	`true`	When false, the dropdown stays open even when the input loses focus.
`autoFocus`	`boolean`	`true`	Focus the input on mount (Tier 1 only).
`onFocus`	`() => void`	—	Called when the input gains focus.
`onBlur`	`() => void`	—	Called when the input loses focus.
`maskCompletedText`	`boolean`	`false`	Strip completed-param text from network requests (PII masking).
`optionOverrides`	`Record<string, (query) => SuggestionOption[]>`	—	Override option lists per suggestion type.
`onSubmit`	`(result) => void`	—	Called on Enter or submit.
`onError`	`(error) => void`	—	Called when a fetch fails.
`onChange`	`(text: string) => void`	—	Called when text changes.
`onParamsChange`	`(params) => void`	—	Called when params change.

Instance methods

Methods are available on the instance after construction. Tier 3 (headless) leans heaviest on these.

Prop	Type	Default	Description
`focus()`	`() => void`	—	Focus the input.
`blur()`	`() => void`	—	Blur the input (Tier 1 only).
`reset()`	`() => void`	—	Clear all state, re-fetch.
`destroy()`	`() => void`	—	Cleanup — abort fetches, clear timers, remove listeners.
`setMode(mode)`	`(mode: "light" \| "dark" \| "auto") => void`	—	Switch color mode at runtime.
`setValue(text)`	`(text: string) => void`	—	Set text (controlled mode).
`setCompletedParams(params)`	`(params) => void`	—	Set completed params (controlled mode).
`update(opts)`	`(opts: Partial<Options>) => void`	—	Update multiple options at once (e.g. animations, pillPlacement).
`handleTextChange(text)`	`(text: string) => void`	—	Call when the user types. Handles capitalization, param reconciliation, filter updates.
`handleKeyDown(event)`	`(event: KeyboardEvent) => void`	—	Forward keyboard events. Handles arrow nav, Enter, Tab, Escape.
`setFocused(focused)`	`(focused: boolean) => void`	—	Notify the library that the input has focus. Required for dropdownTrigger "auto" in Tier 2/3 — the dropdown only opens while focused.
`selectOption(option)`	`(option: SuggestionOption) => void`	—	Select a dropdown option. Updates text, creates completed param, triggers shimmer.
`setActiveDropdownIndex(index)`	`(index: number) => void`	—	Set the highlighted option (e.g. for mouse hover).
`setActivePill(index)`	`(index: number) => void`	—	Move the pill at index to the front (active).
`removeLastParam()`	`() => void`	—	Remove last completed param, restore as a pill.
`clearNewParamId()`	`() => void`	—	Clear shimmer animation state.
`getState()`	`() => CoreState`	—	Get a snapshot of the current state.
`subscribe(listener)`	`(listener) => () => void`	—	Subscribe to state changes (fires after derived state settles). Returns an unsubscribe function.
`on(event, handler)`	`(event, handler) => () => void`	—	Subscribe to a specific event. Returns an unsubscribe function.

State (CoreState)

Snapshot of the SDK's reactive state. Read it via getState() or via subscribe(state => ...).

Prop	Type	Default	Description
`text`	`string`	—	Current input text.
`completedParams`	`CompletedParamState[]`	—	Filled parameters.
`suggestions`	`Suggestion[]`	—	All suggestions from server (including placeholder type).
`actionableSuggestions`	`Suggestion[]`	—	Non-placeholder suggestions (the pills).
`filteredOptions`	`SuggestionOption[]`	—	Options for the active suggestion, filtered by the current query.
`segments`	`Segment[]`	—	Input text split into typed text vs completed params — for overlay rendering.
`placeholderText`	`string`	—	Resolved placeholder text (from server or option).
`activeDropdownIndex`	`number`	—	Highlighted option index. -1 = none.
`isDropdownOpen`	`boolean`	—	Whether the dropdown should be visible.
`newParamId`	`string \| null`	—	ID of the most recently added param (for shimmer).
`isLoading`	`boolean`	—	Fetch in progress.
`isReady`	`boolean`	—	Server indicates the query is complete.
`error`	`Error \| null`	—	Last fetch error.

Events

Subscribe to specific events with on(). The returned function unsubscribes.

const off = ac.on("submit", (result) => console.log(result));
off(); // unsubscribe

// Available events: "submit" | "error" | "change" | "paramsChange" | "focus" | "blur"