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. |
apiConfigRequired | 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. |
showProducts | boolean | true | Render the product strip below the options whenever there are products to show: by default the items the /suggest response reports as matching the query, or the results of a custom products search. Set to false to render no strip and run no custom search. Turning it back on restores the server's items at once, while a custom products search repopulates on the next request. |
products | ProductsConfig | — | Custom source for the product strip. Omit it and the strip shows the items the /suggest response itself reports as matching the query, with no extra request. Set it and the strip is fed by your own search endpoint on the SDK's existing fetch cadence instead; the server's items are then not rendered. Takes { fetch, transform }: fetch runs your search and must honour the AbortSignal it's handed, transform maps the raw payload to Product[]. |
productsLayout | "row" | "list" | "row" | How the product strip lays its cards out. "row" is a horizontally scrolling shelf. "list" stacks the same cards as full-width rows (thumbnail on the left, title, vendor and price on the right) for results that read as a list, such as courses, listings or documents, rather than products on a shelf. The list scrolls vertically inside --aia-product-list-max-height, 320px by default. update({ productsLayout }) re-lays the strip out at once. |
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[] | What the product strip shows. By default the items the latest /suggest response reported as matching the query, replaced on every response and empty when the response carried none, so the strip never shows items from an older query. With products configured, the results of the latest custom search instead, cleared on an empty query and on a failed search. Always empty while showProducts is false. |
customFields | CustomFieldsReport | null | The catalog report the latest applied response carried, or null when it carried none. Replaced wholesale per response, so it always describes the suggestions on screen. See CustomFieldsReport below. |
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. |
CustomFieldsReport
The catalog report. Every response that read your product catalog also says what it did with the query. It lives on state as customFields, and it rides on AutocompleteResult as custom_fields, so the submit event carries it too.
| Prop | Type | Description |
|---|---|---|
applied_filters | ExpressedFilter[] | Constraints the server read out of the query and the catalog answered, each { param, value, op } with op one of eq, ne, lt, lte, gt, gte. Always an array. |
dropped_filters | ExpressedFilter[] | Constraints the query expressed that the catalog could not answer: a parameter it does not have, a bound that is not a number, or a value no item carries. The items were narrowed without them, so this list is what tells "87 black t-shirts" from "no black item, so here are t-shirts". Always an array. |
items.total | number | How many items the applied filters left standing. Also counts what the query's own words matched, so it drops as a typed word starts matching a title. |
items.matched | MatchedItem[] | The items themselves, capped by the server. This is the list the product strip renders. Empty with a non-zero total when nothing narrowed the catalog, since naming arbitrary items as matches would mislead. |
null (no custom_fields key on the result) means the response carried no report: no catalog was read for it, such as a product with no catalog, the starting state, or a response with no option-bearing parameter to offer. That is "no news", not an empty catalog. The strip clears on such a response rather than keeping an older query's items, and the report stays readable while showProducts is false.
Events
Subscribe to specific events with on(). The returned function unsubscribes.
events.ts
const off = ac.on("submit", (result) => console.log(result));off(); // unsubscribe// Available events: "submit" | "error" | "change" | "paramsChange"// "stateChange" | "focus" | "blur" | "productSelect"