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).
`additionalContext`	`Record<string, unknown>`	—	Optional user context. Include whatever you know about the user (a profile, preferences, workspace, anything) to personalize suggested parameters and options to them.
`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"`	`"dropdown"`	Where unfilled pills render. Ignored in "dropdown" render mode, which always puts them in the dropdown.
`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`	When false, options the server marked is_tappable: false (hint rows like "or type something else…") are hidden instead of rendered alongside the selectable ones.
`submitButton`	`HTMLElement \| null`	—	Custom submit button. Pass an element to replace the built-in arrow button, or null to render none. Leaving it undefined keeps the default. Clicks on your element bubble up and trigger submit.
`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.
`onStateChange`	`(state: CoreState) => void`	—	Called with the full state snapshot whenever it changes — the option form of subscribe(). Use it when you want state pushed to you at construction time rather than wiring a subscription afterwards.
`value`	`string`	—	Controlled mode: supply the input text yourself. Pair with onChange, which fires on every mutation.
`completedParams`	`CompletedParamState[]`	—	Controlled mode: supply the filled params yourself. Pair with onParamsChange, which fires on every mutation.
`products`	`ProductsConfig`	—	Opt-in product strip. When set, the dropdown renders a row of product cards below the options grid, fed by your own search endpoint on the SDK's existing fetch cadence. Takes { fetch, transform }: fetch runs your search and must honour the AbortSignal it's handed, transform maps the raw payload to Product[]. Omit it and nothing changes — no request, no markup, no layout shift.
`onProductSelect`	`(product: Product) => void`	—	Called when the user activates a product card. The SDK never navigates — you decide what a selection means (open the product page, add to cart, fill the input). Modifier and middle clicks are left to the browser so cmd-click still opens a tab, and don't fire this.

Instance methods

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

Prop	Type	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.
`selectProduct(product)`	`(product: Product) => void`	Announce a product-card activation, firing onProductSelect. The built-in strip calls this for you; call it yourself only if you render your own strip from the products state.
`handleCaretMove(offset)`	`(offset: number \| null) => void`	Report the caret's plain-text offset after a selection-only move. Needed in "dropdown" and "headless" modes, where you own the input: it's what lets the core notice the caret leaving a completed param and exit re-edit mode.
`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	Description
`text`	`string`	Current input text.
`completedParams`	`CompletedParamState[]`	Filled parameters.
`skippedParams`	`SkippedParamState[]`	Suggestions the user dismissed with the skip key (→). They have no text in the input, so they live here rather than in completedParams, and are folded into the wire completed_params array (as text: "skipped") on every request and submit result.
`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`	Placeholder text for the current step, from the server's placeholder-type suggestion.
`activeDropdownIndex`	`number`	Highlighted option index. -1 = none.
`isDropdownOpen`	`boolean`	Whether the dropdown should be visible.
`isFocused`	`boolean`	Whether the input currently has focus. In "dropdown" and "headless" modes this is whatever you last passed to setFocused().
`isActivePillSelected`	`boolean`	Whether the leading pill should render in its selected state (full opacity) rather than de-emphasized. True while the dropdown is open with a tappable option highlighted; always false when dropdownTrigger is "hidden".
`products`	`Product[]`	Results of the latest product search. Always empty unless the products option is configured, and cleared on an empty query or a failed search so the strip never shows results from an older query.
`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"
//                   "stateChange" | "focus" | "blur" | "productSelect"