API Reference

Every prop, hook, and type — distilled.

<AIAutocomplete />

The full drop-in component. Owns the input, dropdown, and pills.

PropTypeDefaultDescription
onSubmitRequired(result: AutocompleteResult) => void—Called on Enter or submit. Receives an AutocompleteResult.
onError(error: Error) => void—Called when a fetch fails.
apiConfigAPIConfig—Runtime API configuration (key or token).
placeholderstring—Fallback placeholder when the server doesn't return one.
classNamestring—Class applied to the container.
columnsnumber2Number of columns in the dropdown grid.
pillPlacement"inline" | "dropdown" | "hidden""inline"Where unfilled pills render. inline lives in the input; dropdown places them with options.
mode"light" | "dark" | "auto""auto"Color mode. auto follows prefers-color-scheme.
optionsPosition"above" | "below""below"Where the dropdown opens relative to the input.
animationsbooleantrueEnable selection streak + new-param shimmer.
dropdownTrigger"auto" | "manual" | "hidden""auto"When the dropdown appears. auto = when options available; manual = only on pill tap.
closeDropdownOnBlurbooleantrueWhen false, the dropdown stays open even when the input loses focus.
autoFocusbooleantrueFocus the input on mount. Set to false to leave focus to the consumer.
onFocus() => void—Called when the input gains focus.
onBlur() => void—Called when the input loses focus.
maskCompletedTextbooleanfalseStrip completed-param text from network requests (PII masking).
optionOverridesRecord<string, (query) => SuggestionOption[]>—Override option lists per suggestion type.
valuestring—Controlled text value.
completedParamsCompletedParamState[]—Controlled completed params.
onChange(value: string) => void—Called when text changes (controlled mode).
onParamsChange(params: CompletedParamState[]) => void—Called when params change (controlled mode).
refRef<AIAutocompleteHandle>—Imperative handle: focus(), blur(), reset(), setMode().

useAIAutocomplete()

Use the hook for custom rendering. Same options as <AIAutocomplete /> minus the rendering-only props (className, mode, optionsPosition, animations, pillPlacement, autoFocus). The hook doesn't own the textarea — onFocus and onBlur fire when the consumer-owned textarea's focus changes.

State

PropTypeDefaultDescription
completedParamsCompletedParamState[]—Filled parameters.
suggestionPillsSuggestion[]—Unfilled suggestions (pills). First item is the active pill.
segmentsSegment[]—Input text split into typed text vs completed segments.
newParamIdstring | null—ID of the most recently added param (for shimmer).
suggestionsSuggestion[]—All suggestions from server (including placeholder type).
activeIndexnumber—Highlighted option index. -1 = none.
isLoadingboolean—Fetch in progress.
isReadyboolean—Server indicates query is complete.
isDropdownOpenboolean—Whether the dropdown should be visible. Drive your own dropdown's visibility with this in Tier 3.
placeholderTextstring—Suggested placeholder text for the current step.
errorError | null—Last fetch error.

Input forwarding (custom inputs)

PropTypeDefaultDescription
handleTextChange(text: string) => void—Forward the input's current plain text to the engine on every edit. Custom inputs only — textareas use inputProps.
handleKeyDown(e: KeyboardEvent) => void—Forward a keyboard event so the engine can handle Arrow/Enter/Tab/Escape while the dropdown is open. Check event.defaultPrevented to see if it was consumed. Custom inputs only.
setFocused(focused: boolean) => void—Tell the engine the input gained or lost focus. Custom inputs only.
handleCaretMove(offset: number) => void—Report the caret position (plain-text offset) so arrow keys can move into the dropdown. Call on selection changes. Custom inputs only.

Actions

PropTypeDefaultDescription
setActivePill(index: number) => void—Move the pill at index to front (active).
removeLastParam() => void—Remove last completed param, restore as a pill.
clearNewParamId() => void—Clear shimmer animation state.
reset() => void—Clear all state, re-fetch.

Spread props

PropTypeDefaultDescription
inputPropsTextareaHTMLAttributes—Spread onto a <textarea>. Includes value, placeholder, onChange, onKeyDown, and ARIA attributes.
dropdownPropsAIAutocompleteDropdownProps—Spread onto <AIAutocompleteDropdown />. Its shape is exactly the <AIAutocompleteDropdown /> props documented below — in Tier 3, read suggestions, activeIndex, isOpen, onSelect, and onHighlight from it to render your own dropdown.

inputProps fields

What inputProps contains, for when you want to add a handler or wire a non-textarea input. Spread it onto a <textarea>; for a contentEditable or rich-text input, skip it and use the input-forwarding actions above.

PropTypeDefaultDescription
valuestring—Current input text — render it as the textarea's value.
placeholderstring | undefined—Suggested placeholder for the active step (may be undefined).
onChange(e: ChangeEvent<HTMLTextAreaElement>) => void—Forwards edits to the engine (also handles autocapitalize).
onKeyDown(e: KeyboardEvent<HTMLTextAreaElement>) => void—Routes Arrow / Enter / Tab / Escape to the dropdown while it's open.
onFocus / onBlur() => void—Notify the engine when the input gains or loses focus.
role + aria-*ARIA attributes—Combobox accessibility wiring: role="combobox", aria-expanded, aria-activedescendant, aria-autocomplete, aria-controls.

<AIAutocompleteDropdown />

Spread dropdownProps from useAIAutocomplete.

PropTypeDefaultDescription
suggestionsRequiredSuggestion[]—Suggestions to display.
activeIndexRequirednumber—Highlighted option index.
onSelectRequired(option: SuggestionOption) => void—Called when an option is selected.
onHighlightRequired(index: number) => void—Called on mouse hover.
isOpenRequiredboolean—Whether the dropdown is visible.
idRequiredstring—Listbox ID for ARIA.
pillsSuggestion[]—Pills to render inside the dropdown.
onPillClick(index: number) => void—Called when a pill is clicked.
showPillsbooleantrueWhether to render pills.
optionsPosition"above" | "below""below"Where the dropdown opens relative to the input — "above" or "below". Default "below".
mode"light" | "dark" | "auto"—Color mode for a standalone dropdown — self-scopes the SDK tokens so no .magicx-aia wrapper is needed. Leave unset when nested inside a .magicx-aia ancestor.
classNamestring—CSS class applied to the dropdown.

AutocompleteResult

The shape of the object passed to onSubmit.

PropTypeDefaultDescription
querystring—Plain text as the user sees it.
raw_querystring—Text with placeholder tokens (e.g. "Create a {{TASK_1}}").
completed_paramsCompletedParam[]—Filled parameter values.