API Reference | Swift AI Autocomplete Docs

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.

Prop	Type	Default	Description
`apiConfig`Required	`APIConfig`	—	Auth + endpoint configuration: .apiKey(...) or .accessToken(...). See Authentication.
`requestTimeout`	`TimeInterval`	`15`	Per-request timeout, in seconds.
`optionOverrides`	`[String: (String) -> [SuggestionOption]]`	`[:]`	Client-side options per suggestion type — see Advanced.
`maskCompletedText`	`Bool`	`false`	Withholds completed-param text from requests and telemetry. The onSubmit result is unaffected.
`additionalContext`	`JSONValue?`	`nil`	Optional user context sent with every request as additional_context. Include whatever your app knows (a profile, preferences, workspace or session state) to personalize suggested parameters and options. Seeds the controller property of the same name.
`customPlaceholder`	`String?`	`nil`	Overrides the server-suggested placeholder for an empty input.
`dropdownTrigger`	`.auto \| .manual \| .hidden`	`.auto`	When the dropdown may open: on focus (.auto), only after a pill tap (.manual), or never (.hidden).
`closeDropdownOnBlur`	`Bool`	`true`	Close the dropdown when the input loses focus.
`showNonTappableOptions`	`Bool`	`false`	Show header / informational rows in the option list.
`optionsPosition`	`.above \| .below`	`.below`	Render the dropdown above or below the input.
`pillPlacement`	`.inline \| .dropdown \| .hidden`	`.dropdown`	Where unfilled-parameter pills render: inline in the input, in a bar inside the dropdown, or hidden.
`autoFocus`	`Bool`	`true`	Focus 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.

Prop	Type	Description
`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.
`.submitButtonHidden(_:)`	`Bool = true`	Hides the trailing submit button entirely — no built-in arrow and no custom content. Submission still works via the keyboard return key.
`.dropdownHidden(_:)`	`Bool = true`	Detaches the dropdown from the input: the view renders the input alone, and you anchor .aiAutocompleteDropdown to any view sharing the same controller — e.g. a card wrapping the input alongside other controls.
`.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.

Prop	Type	Description
`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.textBinding`	`Binding<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.

Prop	Type	Default	Description
`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.
`controller`	`AIAutocompleteController`	—	The backing controller — read state or call actions directly.
`appearance`	`AIAutocompleteAppearance`	—	Assign a new value to restyle in place.
`submitButtonView`	`UIView?`	`nil`	Custom submit button view; nil uses the built-in button.
`showsSubmitButton`	`Bool`	`true`	Hide 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.

Prop	Type	Description
`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

Prop	Type	Description
`text`	`String`	The raw input string, with {{PLACEHOLDER}} tokens inline.
`segments`	`[Segment]`	Render-ready spans, in order: .text runs, .completed pill spans, and .identified spans (LLM-identified, not re-editable).
`completedParams`	`[CompletedParamState]`	Filled parameters, in order, with their cached options for re-edit.
`identifiedParams`	`[IdentifiedParamState]`	Spans of the user's own text the server identified as parameters — see Advanced. Tentative: each response replaces the set, and an entry drops out when its text stops matching.
`suggestions`	`[Suggestion]`	Current suggestion pills from the server.
`additionalContext`	`JSONValue?`	Mutable: update it as the session evolves and the next request carries the new value. Assigning never fires a request of its own; survives reset(). See Personalization.
`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).
`activeIndex`	`Int`	Index of the active suggestion; -1 when none.
`isDropdownOpen`	`Bool`	Whether the dropdown should be visible — derived from focus, trigger mode, and caret position.
`isLoading`	`Bool`	A fetch is in flight.
`isReady`	`Bool`	Mirrors the server's is_ready flag — the query has enough filled parameters to submit.
`isFocused`	`Bool`	The input has first-responder status.
`placeholder`	`String?`	Server-suggested placeholder for an empty input.
`newParamID`	`UUID?`	ID of a freshly promoted param — drives the shimmer; clear with clearNewParamID().
`editingParam`	`CompletedParamState?`	The completed param being re-edited, if any.
`error`	`AIAutocompleteError?`	Last surfaced error; clear with dismissError().

Actions

Prop	Type	Description
`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 and immediately refetches suggestions conditioned on the answer (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.
`removeIdentifiedParam(atCaret:)`	`(Int) -> Bool`	Deletes the identified chip whose trailing edge sits at the caret offset; returns whether one was removed. Custom inputs call this on Backspace.
`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.

Prop	Type	Description
`query`	`String`	The human-readable query with parameters filled in.
`rawQuery`	`String`	The query with {{PLACEHOLDER}} tokens — send this to your backend.
`completedParams`	`[CompletedParam]`	Every filled parameter: placeholder, type, and text.