API Reference

Every public surface in one place — the configuration, the SwiftUI and UIKit views, and the controller that drives them.

Configuration

Passed to every entry point. All fields except apiConfig have defaults — set only what you need.

PropTypeDefaultDescription
apiConfigRequiredAPIConfig—Auth + endpoint configuration: .apiKey(...) or .accessToken(...). See Authentication.
requestTimeoutTimeInterval15Per-request timeout, in seconds.
optionOverrides[String: (String) -> [SuggestionOption]][:]Client-side options per suggestion type — see Advanced.
maskCompletedTextBoolfalseWithholds completed-param text from requests and telemetry. The onSubmit result is unaffected.
customPlaceholderString?nilOverrides the server-suggested placeholder for an empty input.
dropdownTrigger.auto | .manual | .hidden.autoWhen the dropdown may open: on focus (.auto), only after a pill tap (.manual), or never (.hidden).
closeDropdownOnBlurBooltrueClose the dropdown when the input loses focus.
showNonTappableOptionsBoolfalseShow header / informational rows in the option list.
optionsPosition.above | .below.belowRender the dropdown above or below the input.
pillPlacement.inline | .dropdown | .hidden.dropdownWhere unfilled-parameter pills render: inline in the input, in a bar inside the dropdown, or hidden.
autoFocusBooltrueFocus the input when the Tier 1 view appears.
onSubmit((AutocompleteResult) -> Void)?—Called with the AutocompleteResult when the query is submitted.
onError((AIAutocompleteError) -> Void)?—Called on the main actor for every terminal error. See Advanced.
onFocus(() -> Void)?—Called when the input gains focus.
onBlur(() -> Void)?—Called when the input loses focus.

AIAutocomplete (SwiftUI)

The Tier 1 SwiftUI view. Style it with .aiAutocompleteAppearance(_:) — native modifiers like .font(_:) can't reach the wrapped UIKit view.

PropTypeDefaultDescription
init(configuration:appearance:)(Configuration, AIAutocompleteAppearance)—Creates the view with its own controller.
init(controller:appearance:)(AIAutocompleteController, AIAutocompleteAppearance)—Wraps a controller you hold — share it with Tier 2 code or tests.
.submitButton { }@ViewBuilder () -> some View—Supplies the trailing submit button's visuals; the SDK wires the tap to submit + reset.
.focused(_:)FocusState<Bool>.Binding—Two-way bridge between a @FocusState Boolean and the input's first-responder state.
.aiAutocompleteAppearance(_:)AIAutocompleteAppearance—Sets the appearance for every AIAutocomplete and AIAutocompleteDropdown in the subtree.

AIAutocompleteDropdown (SwiftUI)

The Tier 2 dropdown, paired with your own input through a shared controller.

PropTypeDefaultDescription
AIAutocompleteDropdown(controller:appearance:)View—Standalone dropdown view — place it yourself; it self-sizes vertically.
.aiAutocompleteDropdown(_:appearance:)View modifier—Floats the dropdown over the modified view on the configured edge — the same placement Tier 1 uses.
controller.textBindingBinding<String>—Binding<String> over the controller for wiring TextField / TextEditor; writes route through updateText(_:).

AIAutocompleteView (UIKit)

The Tier 1 UIKit view. It reports its height through intrinsicContentSize and starts/stops fetching on window attach/detach.

PropTypeDefaultDescription
init(configuration:appearance:showsDropdown:)(Configuration, AIAutocompleteAppearance, Bool)—Creates the view with its own controller. showsDropdown: false renders the input only.
init(controller:appearance:showsDropdown:)(AIAutocompleteController, AIAutocompleteAppearance, Bool)—Wraps an existing controller.
controllerAIAutocompleteController—The backing controller — read state or call actions directly.
appearanceAIAutocompleteAppearance—Assign a new value to restyle in place.
submitButtonViewUIView?nilCustom submit button view; nil uses the built-in button.
showsSubmitButtonBooltrueHide or show the submit button.
focus() / blur()() -> Bool—Make or resign first responder. Returns whether the change took effect.
reset()() -> Void—Clears state for a fresh session (same as controller.reset()).

AIAutocompleteDropdownView (UIKit)

The Tier 2 dropdown for UIKit — add it near your input and share the controller.

PropTypeDefaultDescription
init(controller:appearance:)(AIAutocompleteController, AIAutocompleteAppearance)—Creates the dropdown over a shared controller.
moveHighlight(by:)(Int) -> Void—Moves the keyboard highlight by a delta (hardware arrow keys).
selectHighlighted()() -> Bool—Selects the highlighted option; returns false when nothing is highlighted.
clearHighlight()() -> Void—Clears the keyboard highlight.

AIAutocompleteController

The @MainActor, @Observable state machine behind every tier. SwiftUI views that read its properties re-render automatically.

State

PropTypeDefaultDescription
textString—The raw input string, with {{PLACEHOLDER}} tokens inline.
segments[Segment]—Render-ready spans: .text runs and .completed pill spans, in order.
completedParams[CompletedParamState]—Filled parameters, in order, with their cached options for re-edit.
suggestions[Suggestion]—Current suggestion pills from the server.
filteredOptions[SuggestionOption]—Tappable options for the active suggestion, after filtering and overrides.
dropdownPillSuggestions[Suggestion]—Pills for the dropdown's pill bar (pillPlacement: .dropdown, or re-edit).
activeIndexInt—Index of the active suggestion; -1 when none.
isDropdownOpenBool—Whether the dropdown should be visible — derived from focus, trigger mode, and caret position.
isLoadingBool—A fetch is in flight.
isReadyBool—Mirrors the server's is_ready flag — the query has enough filled parameters to submit.
isFocusedBool—The input has first-responder status.
placeholderString?—Server-suggested placeholder for an empty input.
newParamIDUUID?—ID of a freshly promoted param — drives the shimmer; clear with clearNewParamID().
editingParamCompletedParamState?—The completed param being re-edited, if any.
errorAIAutocompleteError?—Last surfaced error; clear with dismissError().

Actions

PropTypeDefaultDescription
start()() -> Void—Fires the initial fetch. Idempotent — safe to call from multiple onAppear hooks.
stop()() -> Void—Cancels in-flight work; state is preserved.
reset()() -> Void—Clears all state and rotates the session ID.
updateText(_:)(String) -> Void—Sets the input text — recomputes segments, promotes exact matches, debounces the fetch.
selectOption(_:)(SuggestionOption) -> Void—Promotes an option into a completed param (what an option tap calls).
setActivePill(_:)(Int) -> Void—Makes the pill at the index active and opens its options.
removeLastParam()() -> Void—Removes the most recent completed param.
submit()() -> Void—Builds the AutocompleteResult and calls onSubmit. Does not reset.
submitAndReset()() -> Void—submit(), then reset(), then start() — the full Tier 2 submit flow.
setFocused(_:)(Bool) -> Void—Reports focus changes from a custom input; drives isDropdownOpen and onFocus/onBlur.
startEditingParam(_:)(UUID) -> Void—Enters re-edit mode for a completed param (what a pill tap calls).
exitEditMode()() -> Void—Leaves re-edit mode without changing the param.
dismissError()() -> Void—Clears the error property.
clearNewParamID()() -> Void—Clears newParamID after your UI has shown the new-param effect.

AutocompleteResult

Handed to onSubmit. Properties are camelCase — the SDK converts to the API's snake_case on the wire.

PropTypeDefaultDescription
queryString—The human-readable query with parameters filled in.
rawQueryString—The query with {{PLACEHOLDER}} tokens — send this to your backend.
completedParams[CompletedParam]—Every filled parameter: placeholder, type, and text.