# AI Autocomplete β full documentation
> AI Autocomplete is a drop-in SDK that helps users discover and complete actions in real time inside any text box. It guides users on what to type, turning a blank input into instant intent β 10X faster and 5X cheaper than traditional LLMs, with ~200ms responses. Integrate in minutes via a native SDK (React, Angular, Vanilla JS, Swift) or the HTTP API.
This file is the complete public corpus in one document: every page below is
also available on its own at the same URL with `.md` appended. The curated
index lives at https://ai-autocomplete.com/llms.txt.
## Contents
- [AI Autocomplete SDK | Real-time AI suggestions for any text box](https://ai-autocomplete.com/index.md)
- [Privacy Policy | AI Autocomplete](https://ai-autocomplete.com/legal/privacy.md)
- [Terms of Service | AI Autocomplete](https://ai-autocomplete.com/legal/terms.md)
- [Pricing | AI Autocomplete](https://ai-autocomplete.com/other/pricing.md)
- [FAQ | AI Autocomplete SDK](https://ai-autocomplete.com/other/faqs.md)
- [Enterprise | AI Autocomplete](https://ai-autocomplete.com/other/enterprise.md)
- [Blog | AI Autocomplete](https://ai-autocomplete.com/blog.md)
- [AI Autocomplete for Shopify | Increase Conversions From Search](https://ai-autocomplete.com/ecommerce/shopify.md)
- [AI Autocomplete for Magento | Increase Conversions From Search](https://ai-autocomplete.com/ecommerce/magento.md)
- [AI Autocomplete for WooCommerce | Increase Conversions From Search](https://ai-autocomplete.com/ecommerce/woocommerce.md)
- [AI Autocomplete for E-commerce | Increase Conversions From Search](https://ai-autocomplete.com/ecommerce/search.md)
- [AI Autocomplete SDK: Give Every Text Box a Brain](https://ai-autocomplete.com/blog/ai-autocomplete-launch.md)
- [AI Autocomplete Software: A Practical Buyer's Guide](https://ai-autocomplete.com/blog/ai-autocomplete-software-buyers-guide.md)
- [AI Text Completion vs AI Autocomplete: Key Differences](https://ai-autocomplete.com/blog/ai-text-completion-vs-ai-autocomplete.md)
- [What Is AI Autocomplete? The Intent Layer for AI](https://ai-autocomplete.com/blog/what-is-ai-autocomplete-intent-layer.md)
- [Traditional Autocomplete vs AI Autocomplete: Key Differences](https://ai-autocomplete.com/blog/traditional-autocomplete-vs-ai-autocomplete.md)
- [AI Autocomplete vs Algolia and Elasticsearch Autocomplete](https://ai-autocomplete.com/blog/ai-autocomplete-vs-algolia-elasticsearch-autocomplete.md)
- [How AI Autocomplete Works with Algolia or Elasticsearch](https://ai-autocomplete.com/blog/how-ai-autocomplete-works-with-algolia-or-elasticsearch.md)
- [AI Autocomplete Benefits: 7 Ways Better Input Wins](https://ai-autocomplete.com/blog/ai-autocomplete-benefits.md)
- [AI Autocomplete for Ecommerce: Better Product Search](https://ai-autocomplete.com/blog/ai-autocomplete-for-ecommerce.md)
- [AI Autocomplete for Site Search: Better Queries, Results](https://ai-autocomplete.com/blog/ai-autocomplete-for-site-search.md)
- [AI Autocomplete for AI Agents: Build a Better First Brief](https://ai-autocomplete.com/blog/ai-autocomplete-for-ai-agents.md)
- [AI Autocomplete for Customer Support: Better Intake](https://ai-autocomplete.com/blog/ai-autocomplete-for-customer-support.md)
- [Search Suggestions vs Semantic Search vs AI Autocomplete](https://ai-autocomplete.com/blog/search-suggestions-vs-search-as-you-type-vs-semantic-search.md)
- [AI Autocomplete vs Search Autocomplete Providers](https://ai-autocomplete.com/blog/ai-autocomplete-vs-search-autocomplete-providers.md)
- [How to Add AI Autocomplete to React in 10 Minutes](https://ai-autocomplete.com/blog/how-to-install-ai-autocomplete-react.md)
- [Autocomplete API vs SDK: Which Integration Is Right?](https://ai-autocomplete.com/blog/autocomplete-api-vs-sdk.md)
- [Build vs Buy AI Autocomplete: The Real Engineering Cost](https://ai-autocomplete.com/blog/build-vs-buy-ai-autocomplete.md)
- [Getting Started | React AI Autocomplete Docs](https://ai-autocomplete.com/docs/react/getting-started.md)
- [Integration Tiers | React AI Autocomplete Docs](https://ai-autocomplete.com/docs/react/integration-tiers.md)
- [API Reference | React AI Autocomplete Docs](https://ai-autocomplete.com/docs/react/api-reference.md)
- [Authentication | React AI Autocomplete Docs](https://ai-autocomplete.com/docs/react/authentication.md)
- [Styling | React AI Autocomplete Docs](https://ai-autocomplete.com/docs/react/styling.md)
- [Advanced | React AI Autocomplete Docs](https://ai-autocomplete.com/docs/react/advanced.md)
- [Getting Started | Angular AI Autocomplete Docs](https://ai-autocomplete.com/docs/angular/getting-started.md)
- [Integration Tiers | Angular AI Autocomplete Docs](https://ai-autocomplete.com/docs/angular/integration-tiers.md)
- [API Reference | Angular AI Autocomplete Docs](https://ai-autocomplete.com/docs/angular/api-reference.md)
- [Authentication | Angular AI Autocomplete Docs](https://ai-autocomplete.com/docs/angular/authentication.md)
- [Styling | Angular AI Autocomplete Docs](https://ai-autocomplete.com/docs/angular/styling.md)
- [Advanced | Angular AI Autocomplete Docs](https://ai-autocomplete.com/docs/angular/advanced.md)
- [Getting Started | JavaScript AI Autocomplete Docs](https://ai-autocomplete.com/docs/vanilla/getting-started.md)
- [Integration Tiers | JavaScript AI Autocomplete Docs](https://ai-autocomplete.com/docs/vanilla/integration-tiers.md)
- [API Reference | JavaScript AI Autocomplete Docs](https://ai-autocomplete.com/docs/vanilla/api-reference.md)
- [Authentication | JavaScript AI Autocomplete Docs](https://ai-autocomplete.com/docs/vanilla/authentication.md)
- [Styling | JavaScript AI Autocomplete Docs](https://ai-autocomplete.com/docs/vanilla/styling.md)
- [Advanced | JavaScript AI Autocomplete Docs](https://ai-autocomplete.com/docs/vanilla/advanced.md)
- [Getting Started | HTTP API AI Autocomplete Docs](https://ai-autocomplete.com/docs/http/getting-started.md)
- [Authentication | HTTP API AI Autocomplete Docs](https://ai-autocomplete.com/docs/http/authentication.md)
- [API Reference | HTTP API AI Autocomplete Docs](https://ai-autocomplete.com/docs/http/api-reference.md)
- [Advanced | HTTP API AI Autocomplete Docs](https://ai-autocomplete.com/docs/http/advanced.md)
- [Getting Started | Swift AI Autocomplete Docs](https://ai-autocomplete.com/docs/swift/getting-started.md)
- [Integration Tiers | Swift AI Autocomplete Docs](https://ai-autocomplete.com/docs/swift/integration-tiers.md)
- [API Reference | Swift AI Autocomplete Docs](https://ai-autocomplete.com/docs/swift/api-reference.md)
- [Authentication | Swift AI Autocomplete Docs](https://ai-autocomplete.com/docs/swift/authentication.md)
- [Styling | Swift AI Autocomplete Docs](https://ai-autocomplete.com/docs/swift/styling.md)
- [Advanced | Swift AI Autocomplete Docs](https://ai-autocomplete.com/docs/swift/advanced.md)
---
# AI Autocomplete SDK | Real-time AI suggestions for any text box
> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path β the homepage is at `/index.md`.
Add real-time AI suggestions to any text box. AI Autocomplete guides users to what your product can do: search, commerce, agents, and more. 200ms responses, live in minutes.
Source: https://ai-autocomplete.com/
---
The AI Autocomplete SDK
## Users convert when they know what to type.
Add AI Autocomplete to any text box and increase conversions 50% or more. Instead of making people guess, it tells them exactly what your product can do, so they get what they want faster.
Book a demo Try it live
- Search
- Commerce
- Media Generation
- Agents & Software
- Customer service
Compare the difference:
- [](https://ai-autocomplete.com/preview/instacart-9e9f2f)
- [](https://ai-autocomplete.com/preview/replit-959395)
- [](https://ai-autocomplete.com/preview/canva-03bea3)
- [](https://ai-autocomplete.com/preview/snackpass-8d2635)
- [](https://ai-autocomplete.com/preview/suno-ec1ea3)
- [](https://ai-autocomplete.com/preview/cotopaxi-503884)
- [](https://ai-autocomplete.com/preview/compass-e1f384)
- [](https://ai-autocomplete.com/preview/cameo-5165c9)
- [](https://ai-autocomplete.com/preview/kalshi-f63be7)
- [](https://ai-autocomplete.com/preview/rippling-bf6cb6)
AI Autocomplete increases your conversions by guiding users with what your product can do.
 See announcement
The problem
## The blank text box is where intent goes to die.
You shipped a powerful product and put a blinking cursor in an empty box. Users hesitate, under-ask, and leave.
1. 01
### Blank-box paralysis
Users don't know what your product can do, so they type the bare minimum, or nothing at all.
2. 02
### Endless back-and-forth
Vague requests trigger follow-up questions. Every extra round trip costs you users, time, and tokens.
3. 03
### Invisible features
Your best capabilities sit one prompt away, and most users never find them.
AI Autocomplete fixes it at the keystroke, completing every user's thought with things your product can actually do.
Use cases
## Works for every text box.
Wherever your users type, autocomplete turns hesitation into action.
### Search
Read intent mid-keystroke and take users straight to the right result, not a page of maybes.
Watch it in action
### Commerce
Complete vague wishes into full carts: brand, variant, and checkout in a single suggestion.
Watch it in action
### Media generation
Guide users to the prompt that produces the image, video, or deck they pictured.
Watch it in action
### Agents & software
Capture a build-ready spec up front so your agent executes instead of interrogating.
Watch it in action
### Customer service
Get the whole problem in the first message, and resolve it without opening a ticket.
Watch it in action
How it works 01
## Educate your users at the exact moment they type.
The more your product can do, the less of it users discover on their own. Autocomplete turns every keystroke into a guided tour of your best features.
How it works 02
## Capture full intent. Act instantly.
Your agent can only act when it has enough to go on.
Autocomplete gathers the complete request up front. No interrogation, no drop-off.
Ready to take action
How it works 03
## Your UI, your rules. SDK or API.
Ship the fully customizable native SDK today and match your brand down to the pixel.
Want to own the whole surface? Build your own UI straight on the API.
The numbers
## Fast to ship. Faster to run.
10 min
To go live
From API key to live suggestions in your product with one drop-in component.
200 ms
Response time
Our proprietary action engine answers in 200ms, 10X faster than an LLM round trip.
5 X
Cheaper
A fraction of the cost of traditional LLM calls, at production scale.
Ship it
## Drop it in this afternoon.
A few lines in front of the text box you already have. Native SDKs for every major framework, or hit the API directly.
1. 01
### Install the SDK
One package for your framework: React, Vue, Angular, Swift, or plain JS.
2. 02
### Drop it in front of your text box
The component wraps the input you already ship. No rewrite, no redesign.
3. 03
### Go live
Point suggestions at your product's actions and watch intent complete.
**Your text box, upgraded**
```tsx
import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-react";
export function SearchBox() {
return (
search(result.query)}
/>
);
}
```
## \3. Add a key without exposing a secret
For the first integration, create a public key and add it to the application's local environment file. Public keys use the **pk_v1_** prefix, are scoped and rate-limited, and are designed for client-side use.
The environment-variable name depends on the build tool. Vite exposes variables that begin with **VITE_**. Next.js uses **NEXT_PUBLIC_**. Create React App uses **REACT_APP_**. Never place a secret key with the **sk_v1_** prefix in a browser bundle.
For production, the recommended setup keeps the secret key on your server. Your backend exchanges it for a short-lived access token, and the component receives a **getAccessToken** callback. The SDK refreshes before expiry and deduplicates concurrent refreshes. The [Authentication guide](https://ai-autocomplete.com/docs) includes the server and browser code.
**.env**
```bash
VITE_MAGICX_PUBLIC_KEY=pk_v1_your_public_key
```
## \4. Connect product data, styling, and production behavior
A generic model can suggest general details. A useful product integration also supplies the options that are true now: products, contacts, locations, inventory, prices, plans, permissions, or other application data. Runtime option overrides let the host application provide those values when the corresponding field becomes active.
The drop-in component implements the ARIA combobox pattern. Arrow keys navigate suggestions, Tab completes, Enter submits, and Escape closes the dropdown. If the application builds a custom surface with the hook or HTTP API, it also takes ownership of that accessibility behavior.
Before release, test fast typing, slow networks, token expiry, empty states, keyboard-only use, mobile layout, and the exact mapping from completed fields to the downstream call. The [React documentation](https://ai-autocomplete.com/docs) covers styling, controlled state, runtime options, and the full API reference.
## The complete installation path
- **Install one package:** @magicx-eng/ai-autocomplete-react.
- **Render AIAutocomplete** with apiConfig, placeholder, and onSubmit.
- **Use a public key for the first run;** never put a secret key in client code.
- **Use short-lived access tokens for production** when the server can hold the secret key.
- **Pass result.query and completed_params** into the search or action the application already owns.
## Frequently asked questions
### Which React package installs AI Autocomplete?
Install **@magicx-eng/ai-autocomplete-react**. It exports the drop-in AIAutocomplete component, a hook for custom rendering, and the supporting input and dropdown primitives.
### Is a public key safe in a React app?
Public keys with the pk_v1_ prefix are scoped and rate-limited for client use. Never expose a secret key. For production, the recommended mode keeps the secret server-side and gives the browser short-lived access tokens.
### Can I use my existing search function?
Yes. Call the existing function from onSubmit with result.query and any structured parameters needed for filters. AI Autocomplete does not require a new search backend.
### Can I customize the interface?
Yes. Start with the component and CSS variables, use the hook plus provided dropdown for more layout control, or use the hook or HTTP API to own the whole UI. The [API vs SDK guide](https://ai-autocomplete.com/blog/autocomplete-api-vs-sdk) explains the tradeoff.
### Does the SDK handle rapid typing?
Yes. The SDK handles the per-keystroke request loop, cancellation, stale-response protection, token refresh, and interaction state. Direct API integrations must implement those concerns themselves.
## Put the intent layer in the React tree
The first version is one component. The production version can grow without replacing the downstream system.
Open the [React documentation](https://ai-autocomplete.com/docs) or compare [the SDK with the HTTP API](https://ai-autocomplete.com/blog/autocomplete-api-vs-sdk).
Keep exploring: [Documentation](https://ai-autocomplete.com/docs) Β· [Pricing](https://ai-autocomplete.com/other/pricing) Β· [Enterprise](https://ai-autocomplete.com/other/enterprise) Β· [FAQs](https://ai-autocomplete.com/other/faqs)
---
# Autocomplete API vs SDK: Which Integration Is Right?
> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path β the homepage is at `/index.md`.
Choose between an autocomplete SDK and API based on UI ownership, accessibility, request control, platform needs, engineering time, and maintenance cost.
Source: https://ai-autocomplete.com/blog/autocomplete-api-vs-sdk
---
## Autocomplete API or SDK? How to choose the right integration
Comparison Β· By the AI Autocomplete team Β· 7 min read
The model is the same. The difference is how much of the interface and request loop your team wants to own.
An autocomplete SDK and an autocomplete API are not two quality tiers. They are two boundaries around responsibility. The SDK ships a working interaction. The API returns the underlying suggestions and leaves the interaction to the application.
Choosing well requires an honest view of the interface you need, the platforms you support, the engineering time available now, and the maintenance burden you are willing to keep later.
> Choose the SDK for a product surface. Choose the API for a product primitive.
## Start with the part of the experience you need to own
The quickest decision comes from four questions. If the answers point in one direction, avoid turning the integration into an architecture debate.
Ask:
- Do we want a ready input, dropdown, pills, keyboard behavior, loading state, and error state?
- Does the autocomplete need to live inside a custom editor, canvas, command bar, voice surface, or native control?
- Can the team own per-keystroke cancellation, stale responses, focus state, accessibility, token refresh, and analytics?
- Will several platforms share one interaction model, or does each platform need a deliberately different interface?
A standard search box in React or Vanilla JavaScript normally points to the SDK. A custom rich-text editor, backend service, unsupported platform, or deeply embedded workflow may point to the API.
## Use the SDK when speed and interaction quality matter most
The SDK handles the parts that appear simple until users type quickly, press keys in an unexpected order, edit a completed field, lose focus, or hit a slow network. It owns the request loop and a coherent input state rather than handing the application a bag of callbacks.
The drop-in component also gives the team a working accessibility baseline. The React SDK implements the combobox pattern, keyboard navigation, active-descendant state, selectable options, pills, loading, and submission. Styling and runtime option data remain configurable.
> An SDK is not only fewer lines of setup. It is fewer interaction states for the host application to invent and maintain.
Choose this path when the product wants to ship a conventional autocomplete surface quickly, the provided rendering can fit the design system, and the team's differentiation lives in the intent model and downstream experience rather than the mechanics of the text box.
## Use the API when the interaction itself is product-specific
The HTTP API exposes the autocomplete loop directly. The application sends the current raw query, completed parameters, and request metadata, then renders returned suggestions in any form it chooses.
That control is useful for native or unsupported platforms, server-side workflows, voice, custom editors, collaborative canvases, non-visual surfaces, or a design where suggestions do not belong in a conventional dropdown. It also lets one backend broker authentication and policy for several clients.
Control brings obligations. Direct callers must debounce or otherwise manage request volume, cancel or ignore stale requests, maintain session IDs, construct placeholder tokens, refresh access tokens, handle one-shot retry, implement accessibility, and keep rendering state consistent. The [HTTP API documentation](https://ai-autocomplete.com/docs) specifies the request and response shapes.
## A layered integration often gives the best long-term path
Teams do not have to make one permanent choice for every surface. Start with the SDK to validate the intent model and downstream value. Move a specialized surface to the hook or API only when a real interface requirement appears.
Within React, the boundary is already graduated: use the full component, use the hook with the provided dropdown, or use the hook with custom rendering. The HTTP API sits below those options when the application needs to own the transport and state machine too.
This sequence prevents premature infrastructure work. It also makes the custom build easier to specify because the team has observed real users and knows which SDK behavior must be preserved. The [React installation guide](https://ai-autocomplete.com/blog/how-to-install-ai-autocomplete-react) starts with the simplest tier.
## The decision in one page
- **SDK:** fastest route to a complete, accessible product surface.
- **API:** maximum control over rendering, transport, and unsupported platforms.
- **The API creates more ownership:** cancellation, stale responses, auth refresh, sessions, accessibility, and state.
- **The SDK still allows product data and styling;** ready-made does not mean generic content.
- **Start at the highest useful layer** and move lower only when a concrete requirement demands it.
## Frequently asked questions
### What is an autocomplete SDK?
It is a client library that packages the autocomplete request loop and interface behavior. Depending on the integration tier, it can provide the full component, state hook, input props, dropdown, accessibility, and token handling.
### What does an autocomplete API return?
The AI Autocomplete HTTP API returns suggestions for the current raw query and completed parameters, plus request metadata and a parsed view of the input. The caller decides how to render and select them.
### Is the API more powerful than the SDK?
It offers lower-level control, not a better intent model. The SDK uses the same service and exposes customization tiers. Use the API when the application needs a boundary the SDK does not provide.
### Can we begin with the SDK and move to the API later?
Yes. The concepts and result shape carry over. Starting with the SDK can validate the use case before the team takes ownership of a custom rendering and request state machine.
### Which option is better for React?
Use the React SDK unless the input must be embedded in a highly custom surface that cannot use the component or hook. The SDK offers three rendering tiers before a direct API integration becomes necessary.
## Own the layer that makes the product different
Do not rebuild interaction plumbing merely to prove that you can. Do not accept a fixed UI when the interaction is the product.
Compare the full options in the [documentation](https://ai-autocomplete.com/docs) or read the [build-vs-buy guide](https://ai-autocomplete.com/blog/build-vs-buy-ai-autocomplete).
Keep exploring: [Documentation](https://ai-autocomplete.com/docs) Β· [Pricing](https://ai-autocomplete.com/other/pricing) Β· [Enterprise](https://ai-autocomplete.com/other/enterprise) Β· [FAQs](https://ai-autocomplete.com/other/faqs)
---
# Build vs Buy AI Autocomplete: The Real Engineering Cost
> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path β the homepage is at `/index.md`.
A practical build-vs-buy guide to AI autocomplete, covering latency, cancellation, caching, auth, accessibility, analytics, quality, and ongoing ownership.
Source: https://ai-autocomplete.com/blog/build-vs-buy-ai-autocomplete
---
## Build vs buy AI autocomplete: what the production system really requires
Comparison Β· By the AI Autocomplete team Β· 8 min read
A model can produce a plausible completion in an afternoon. A production autocomplete system has to produce the right interaction on every keystroke, under real latency, security, and accessibility constraints.
Build-vs-buy discussions often compare an API price with the cost of one model call. That comparison leaves out the product wrapped around the model: request shaping, latency control, state, evaluation, auth, caching, interface behavior, and the work of operating all of it.
Buying is not automatically cheaper, and building is not automatically more strategic. The right choice depends on whether autocomplete is core intellectual property, how unusual the interaction must be, and whether the team wants to own the system after launch.
> The hard part of AI autocomplete is not generating one completion. It is making thousands of partial requests feel like one reliable interface.
## Define the production system before pricing the build
The visible feature is a text box and a dropdown. Beneath it, a production implementation needs several connected systems. If any one is omitted from the estimate, the internal option will look cheaper than it is.
At minimum, include:
- **Intent and quality:** prompt or model logic, product context, structured fields, live options, safety rules, and an evaluation set.
- **Real-time transport:** debouncing, cancellation, stale-response protection, caching, fallbacks, rate limits, and latency monitoring.
- **Client interaction:** focus, selection, editing, keyboard navigation, mobile behavior, loading, errors, accessibility, and design-system integration.
- **Operations:** keys and tokens, tenant isolation, observability, analytics, abuse controls, releases, incident response, and ongoing model changes.
The list is not an argument against building. It is the scope of what is being built. A fair estimate includes the first implementation, the platform work that multiple teams may share, and the recurring ownership after the original engineer moves on.
## Per-keystroke AI has a different engineering shape
A chat request can wait a second and still feel normal. Autocomplete interrupts the act of typing. Suggestions that arrive late are not merely slow; they can apply to an older query, move the active option, or cause the user to select something that no longer matches the text.
The client has to cancel or ignore old work, preserve completed parameters while text changes, decide when to open and close the dropdown, and handle a response arriving after another response. The server has to keep latency and cost low enough for repeated calls and unpredictable typing bursts.
> A late chat answer is annoying. A late autocomplete answer can be wrong for the text currently on screen.
Caching helps, but intent is contextual. The system must know which parts of a request are reusable, which depend on the tenant or user, and which options must stay live. A naive cache can make the interface fast and incorrect.
## Building makes sense when ownership creates lasting advantage
An internal build can be right when the interaction is central to the product, the team has deep search or real-time UI expertise, the data or deployment model cannot use a hosted service, or the intent engine itself is proprietary and expected to differentiate the company for years.
The strongest build case includes people who will own evaluation, client libraries, infrastructure, security, and product analyticsβnot only a prototype. It also includes enough usage to justify fixed engineering and operational cost, plus requirements a vendor genuinely cannot meet.
Build selectively when possible. A company may own its custom input surface and use an API for intent generation, or use an SDK but inject proprietary product fields and option logic. The [API vs SDK guide](https://ai-autocomplete.com/blog/autocomplete-api-vs-sdk) describes those boundaries.
## Buying makes sense when the capability should compound elsewhere
A managed system is attractive when the team wants to validate the user value quickly, standard interaction behavior is acceptable, several platforms need supported clients, or the internal roadmap has better places to spend search, infrastructure, and accessibility expertise.
Evaluate the vendor as a production dependency. Test latency at realistic geography and concurrency, structured output quality, runtime data, accessibility, auth modes, data handling, rate limits, observability, customization, export paths, incident history, pricing at expected usage, and what happens if the service is unavailable.
Run the decision against cost per successful outcome, not cost per request. Include engineering time, infrastructure, model usage, support, on-call, failed tasks, and the opportunity cost of delaying the feature. Then revisit the choice when usage, requirements, or team capabilities change.
## A fair build-vs-buy decision
- **Price the production system, not the model call.**
- **Autocomplete needs real-time state and latency engineering** that chat prototypes can avoid.
- **Build when ownership is durable advantage** and the team can support the whole surface.
- **Buy when speed, supported interaction, and displaced roadmap work matter more** than owning the plumbing.
- **Hybrid boundaries are normal.** Own the distinctive layer and buy the commodity layer.
## Frequently asked questions
### How hard is it to build AI autocomplete?
A prototype is straightforward. Production difficulty comes from low latency, request cancellation, stale responses, structured state, live data, accessibility, authentication, evaluation, analytics, and ongoing operations.
### When should a company build its own?
Build when autocomplete is core product IP, requirements are genuinely unusual, hosted deployment is impossible, or usage and in-house expertise justify sustained ownership across model, infrastructure, and client layers.
### When should a company buy?
Buy when the goal is to ship and validate quickly, standard SDK or API boundaries fit, and the team would create more value in the domain experience than in maintaining autocomplete infrastructure.
### What should a vendor evaluation include?
Test realistic latency, quality on real partial inputs, structured fields, runtime data, accessibility, auth, privacy, tenant isolation, reliability, rate limits, observability, customization, pricing, support, and failure behavior.
### Can we use a hybrid approach?
Yes. Common boundaries include a custom UI on a managed API, a managed SDK with proprietary runtime options, or an internal orchestration layer that routes between autocomplete, search suggestions, and direct retrieval.
## Build the advantage, not the plumbing by habit
Make the ownership boundary explicit before comparing costs.
Start with the [SDK and API documentation](https://ai-autocomplete.com/docs), or review [enterprise options](https://ai-autocomplete.com/other/enterprise) for custom requirements.
Keep exploring: [Documentation](https://ai-autocomplete.com/docs) Β· [Pricing](https://ai-autocomplete.com/other/pricing) Β· [Enterprise](https://ai-autocomplete.com/other/enterprise) Β· [FAQs](https://ai-autocomplete.com/other/faqs)
---
# Getting Started | React AI Autocomplete Docs
> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path β the homepage is at `/index.md`.
Getting Started guide for integrating the AI Autocomplete SDK with React. Code examples, setup, and API reference.
Source: https://ai-autocomplete.com/docs/react/getting-started
---
Add AI Autocomplete to a React app in under five minutes. Works with React 17+, Next.js, Remix, and Vite.
## Install with an AI agent
Let your AI coding agent set up the integration and walk you through the two browser steps.
Paste this into your agent. It will scaffold the integration and tell you exactly what to do in the browser to finish setup.
**Agent prompt**
```bash
Install AI Autocomplete using the instructions at https://ai-autocomplete.com/install/react.md
```
Works with Claude Code, Cursor, Windsurf, GitHub Copilot, ChatGPT β any agent that can read URLs and run shell commands. [View the prompt](https://ai-autocomplete.com/install/react.md)
## Install
Install the React SDK with your package manager:
**Terminal**
```bash
pnpm add @magicx-eng/ai-autocomplete-react
```
If your app doesn't already have React installed:
**Terminal**
```bash
pnpm add react react-dom
```
## Render the component
Drop the component into your app. Pass an apiConfig and an onSubmit β that's the whole minimal setup.
**App.tsx**
```tsx
import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-react";
export function App() {
return (
{
console.log(result.query); // "Create a email"
console.log(result.raw_query); // "Create a {{TASK_1}}"
console.log(result.completed_params); // [{ placeholder, type, ... }]
}}
className="my-autocomplete"
/>
);
}
```
## Authentication
Grab a [public key](https://ai-autocomplete.com/account/keys) from your account and set it as an environment variable. Public keys are safe to ship in client bundles.
**.env**
```bash
# Add to your .env β never commit this file
VITE_MAGICX_PUBLIC_KEY=pk_v1_your_public_key
```
Security
Public keys are scoped and safe in client bundles, but for production we recommend the secret key + access token flow β your server holds the secret key and mints short-lived tokens for the browser. See Authentication.
## What's next
Next, walk through the integration tiers to choose between the drop-in component and the headless hook, then explore the API reference.
---
# Integration Tiers | React AI Autocomplete Docs
> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path β the homepage is at `/index.md`.
Integration Tiers guide for integrating the AI Autocomplete SDK with React. Code examples, setup, and API reference.
Source: https://ai-autocomplete.com/docs/react/integration-tiers
---
Three ways to integrate, from drop-in to fully headless β pick the one matching how much UI you want to own.
Tier 1
### Full component
Drop-in console.log(result)}
/>
);
}
```
### Controlled state
Pass value + completedParams + their setters to drive state externally. Useful inside form libraries or wizards. (This also works with the hook in Tier 2 and Tier 3.)
**ControlledAutocomplete.tsx**
```tsx
const [text, setText] = useState("");
const [params, setParams] = useState([]);
console.log(result)}
/>;
```
### Imperative ref
Forward a ref to call focus(), reset(), or setMode() imperatively from the parent.
**ImperativeRef.tsx**
```tsx
import { useRef } from "react";
import {
AIAutocomplete,
type AIAutocompleteHandle,
} from "@magicx-eng/ai-autocomplete-react";
const ref = useRef(null);
// ref.current?.focus();
// ref.current?.blur();
// ref.current?.reset();
// ref.current?.setMode("dark");
Submit
`,
})
export class SearchComponent implements OnInit, OnDestroy {
ac!: AIAutocompleteController;
ngOnInit(): void {
this.ac = new AIAutocompleteController({
apiConfig: { apiKey: "pk_v1_your_public_key" },
});
}
submit(): void {
sendToBackend(this.ac.getState().text, this.ac.getState().completedParams);
this.ac.reset(); // start a new session
}
ngOnDestroy(): void {
this.ac.destroy(); // release subscriptions + core
}
}
```
The [aiaInput] directive wires your input's events into the controller and mirrors state into ARIA attributes. renders the pills + options from the same controller. It's absolutely positioned, so place it inside a position: relative element.
### Color mode & position
Pass [mode] ("light", "dark", or "auto") to style a standalone dropdown β it scopes the design tokens to its own root, so no .magicx-aia wrapper is needed. "auto" follows the OS theme. To open it above the input, set optionsPosition: "above" in the controller options β the dropdown reads it from the controller automatically, and arrow-key direction matches since it's the same option. Leave mode unset inside Tier 1, which themes for you.
### Custom & rich-text inputs
[aiaInput] is for a
`,
})
export class SearchComponent implements OnInit, OnDestroy {
ac!: AIAutocompleteController;
ngOnInit(): void {
this.ac = new AIAutocompleteController({
apiConfig: { apiKey: "pk_v1_your_public_key" },
});
}
pick(event: MouseEvent, option: SuggestionOption): void {
event.preventDefault(); // keep focus in the input
this.ac.selectOption(option);
}
ngOnDestroy(): void {
this.ac.destroy();
}
}
```
You still feed the input the same way ([aiaInput] for a textarea, or the controller methods for a custom editor), and you still call destroy() in ngOnDestroy and reset() after submit. Tier 3 only changes who renders the suggestions.
---
# API Reference | Angular AI Autocomplete Docs
> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path β the homepage is at `/index.md`.
API Reference guide for integrating the AI Autocomplete SDK with Angular. Code examples, setup, and API reference.
Source: https://ai-autocomplete.com/docs/angular/api-reference
---
Every input, output, observable, and method β distilled.
##
The full drop-in standalone component. Owns the contentEditable editor, inline pills, dropdown, and all state. Implements ControlValueAccessor for Reactive Forms.
### Inputs
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `apiConfig` | `APIConfig` | β | Runtime API configuration (public key or access token). |
| `additionalContext` | `Record` | β | Optional user context. Include whatever you know about the user (a profile, preferences, workspace, anything) to personalize suggested parameters and options to them. |
| `pillPlacement` | `"inline" \| "dropdown" \| "hidden"` | `"dropdown"` | Where unfilled pills render. inline lives in the input; dropdown places them with the options; hidden shows none. |
| `mode` | `"light" \| "dark" \| "auto"` | `"auto"` | Color mode. auto follows prefers-color-scheme. |
| `optionsPosition` | `"above" \| "below"` | `"below"` | Where the dropdown opens relative to the input. |
| `animations` | `boolean` | `true` | Enable the selection streak + new-param shimmer. |
| `dropdownTrigger` | `"auto" \| "manual" \| "hidden"` | `"auto"` | When the dropdown appears. auto = when options are available; manual = only on pill tap; hidden = never. |
| `closeDropdownOnBlur` | `boolean` | `true` | When false, the dropdown stays open even when the editor loses focus. |
| `showNonTappableOptions` | `boolean` | `true` | Render non-tappable options alongside tappable ones. |
| `columns` | `number` | `2` | Number of columns in the dropdown grid. |
| `maskCompletedText` | `boolean` | `false` | Strip completed-param text from network requests (PII masking). |
| `optionOverrides` | `OptionOverrides` | β | Inject or compute option lists per suggestion type. |
| `autoFocus` | `boolean` | `true` | Focus the editor on mount. Set false to leave focus to the consumer. |
| `value` | `string` | β | Controlled text value. Pair with (valueChange). |
| `completedParams` | `CompletedParamState[]` | β | Controlled completed params. Pair with (completedParamsChange). |
| `submitButton` | `TemplateRef \| null` | β | A to replace the default arrow button. Pass null to render no button. |
| `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. |
### Outputs
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `submitted` | `EventEmitter` | β | Emits on Enter or submit-button click. Carries an AutocompleteResult. |
| `errored` | `EventEmitter` | β | Emits when a fetch fails. |
| `valueChange` | `EventEmitter` | β | Emits when text changes (controlled mode). |
| `completedParamsChange` | `EventEmitter` | β | Emits when completed params change (controlled mode). |
| `focused` | `EventEmitter` | β | Emits when the editor gains focus. |
| `blurred` | `EventEmitter` | β | Emits when the editor loses focus. |
| `productSelect` | `EventEmitter` | β | Emits when the user activates a product card. The SDK never navigates β you decide what a selection means. Modifier and middle clicks are left to the browser and don't emit. |
### Imperative methods
Call these on the component instance via a template reference variable + @ViewChild.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `focus()` | `() => void` | β | Focus the editor. |
| `blur()` | `() => void` | β | Blur the editor. |
| `reset()` | `() => void` | β | Clear all state, rotate the session, and re-fetch. |
| `setMode()` | `(mode: AppearanceMode) => void` | β | Switch color mode at runtime. |
## AIAutocompleteController
A plain TypeScript class β no DI. Create it with new in ngOnInit, hold the reference, and call destroy() in ngOnDestroy. Exposes the SDK's reactive state as RxJS observables plus action methods.
### Constructor options
Pass these to the constructor. Event callbacks (onSubmit, onError, β¦) are registered once at construction β for dynamic reactivity, subscribe to the observables instead.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `apiConfig` | `APIConfig` | β | Runtime API configuration (key or token). |
| `additionalContext` | `Record` | β | Optional user context. Include whatever you know about the user (a profile, preferences, workspace, anything) to personalize suggested parameters and options to them. |
| `optionsPosition` | `"above" \| "below"` | `"below"` | Where the dropdown opens. Read by the keyboard controller to pick the open key. |
| `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` | Render non-tappable options alongside tappable ones. |
| `columns` | `number` | `2` | Number of columns in the dropdown grid. |
| `maskCompletedText` | `boolean` | `false` | Strip completed-param text from network requests (PII masking). |
| `optionOverrides` | `OptionOverrides` | β | Override option lists per suggestion type. |
| `value` | `string` | β | Initial controlled text value. |
| `completedParams` | `CompletedParamState[]` | β | Initial controlled completed params. |
| `onSubmit / onError / onChange` | `(...) => void` | β | onSubmit, onError, onChange, onParamsChange, onFocus, onBlur β registered once at construction. |
| `products` | `ProductsConfig` | β | Opt-in product strip config, same shape as the Tier 1 input. Feeds products$ and the dropdown component's strip. |
| `onProductSelect` | `(product: Product) => void` | β | Called when the user activates a product card. Registered once at construction, like the other callbacks. The SDK never navigates. |
### Observables
Each field is exposed as a stand-alone observable plus a composite state$. All run through distinctUntilChanged + shareReplay, so multiple async pipes share one subscription.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state$` | `Observable` | β | Snapshot of every public field in one object β convenient for *ngIf="ctrl.state$ \| async as state". |
| `dropdown$` | `Observable` | β | Composite stream for the dropdown view (suggestions, activeIndex, isOpen, pills, β¦) β bound to via [controller], or subscribe to it directly to render your own dropdown in Tier 3. |
| `text$` | `Observable` | β | Current editor text. |
| `completedParams$` | `Observable` | β | Filled parameters. |
| `suggestionPills$` | `Observable` | β | Actionable suggestion pills. The first item is the active pill. |
| `segments$` | `Observable` | β | Input text split into typed text vs completed-param segments. |
| `isLoading$` | `Observable` | β | Whether a fetch is in progress (UI-visible). |
| `isDropdownOpen$` | `Observable` | β | Whether the dropdown should be visible. |
| `isReady$` | `Observable` | β | Server indicates the query is complete. |
| `error$` | `Observable` | β | Last fetch error, or null. |
| `activeIndex$` | `Observable` | β | Highlighted dropdown option index. -1 = none. |
| `suggestions$` | `Observable` | β | Every suggestion from the last response, including the placeholder-type one. suggestionPills$ is this list minus the placeholder. |
| `skippedParams$` | `Observable` | β | Suggestions the user dismissed with the skip key (β). Nothing renders them; they're folded into the wire completed_params array on every request and submit result. |
| `placeholderText$` | `Observable` | β | Resolved placeholder text for the current step. |
| `newParamId$` | `Observable` | β | ID of the most recently added param, for driving the shimmer animation. Clear it with clearNewParamId(). |
| `isFocused$` | `Observable` | β | Whether the editor currently has focus, as last reported through the input binder or setFocused(). |
| `isActivePillSelected$` | `Observable` | β | Whether the leading pill should render selected (full opacity) rather than de-emphasized β true while a tappable option is highlighted. |
| `products$` | `Observable` | β | Results of the latest product search. Always empty unless products is configured. |
### Actions
Thin pass-throughs to the headless core. After destroy() they no-op safely.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handleTextChange()` | `(value: string) => void` | β | Call when the user types. Handles capitalization, param reconciliation, and filtering. |
| `handleKeyDown()` | `(e: KeyboardEvent) => void` | β | Forward keyboard events from your input. Handles arrow nav, Enter, Tab, Escape. |
| `setFocused()` | `(focused: boolean) => void` | β | Notify the controller the input gained or lost focus. Custom inputs only β [aiaInput] does this for you. |
| `handleCaretMove()` | `(offset: number \| null) => void` | β | Report the caret position (plain-text offset) so arrow keys can move into the dropdown. Custom inputs only. |
| `selectOption()` | `(option: SuggestionOption) => void` | β | Select a dropdown option β updates text, creates a completed param, triggers shimmer. |
| `selectProduct()` | `(product: Product) => void` | β | Announce a product-card activation, emitting productSelect / calling onProductSelect. The built-in dropdown calls this for you; call it yourself only when rendering your own strip from products$. |
| `setActiveDropdownIndex()` | `(index: number) => void` | β | Highlight a dropdown option by index (-1 = none). Use it to wire hover/keyboard highlighting when rendering your own dropdown. |
| `setActivePill()` | `(index: number) => void` | β | Move the pill at index to the front (active). |
| `removeLastParam()` | `() => void` | β | Remove the last completed param and restore it as a pill. |
| `setValue()` | `(text: string) => void` | β | Set the editor text (controlled mode). |
| `setCompletedParams()` | `(params: CompletedParamState[]) => void` | β | Set completed params (controlled mode). |
| `reset()` | `() => void` | β | Clear all state, rotate the session, and re-fetch. Call after submit. |
| `update()` | `(opts: AIAutocompleteControllerUpdate) => void` | β | Apply runtime option changes (e.g. dropdownTrigger, optionsPosition). Event callbacks can't be swapped β subscribe to the observables instead. |
| `getState()` | `() => AIAutocompleteControllerState` | β | Synchronous snapshot of the current state (for use inside event handlers). |
| `destroy()` | `() => void` | β | Release subscriptions and the underlying core. Call in ngOnDestroy. |
##
Tier 2 dropdown component. Pass it the same controller β it renders the pillbar, options grid, and loading skeleton, and forwards actions back to the controller.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `controller` Required | `AIAutocompleteController` | β | The controller that owns the autocomplete state. |
| `showPills` | `boolean` | `true` | Whether to render the pillbar inside the dropdown. |
| `mode` | `"light" \| "dark" \| "auto"` | β | Color mode for a standalone dropdown β self-scopes the SDK tokens so no .magicx-aia wrapper is needed. "auto" follows prefers-color-scheme. Leave unset when nested inside a .magicx-aia ancestor (e.g. Tier 1). |
| `className` | `string` | β | CSS class applied to the dropdown root. |
## [aiaInput] directive
Attach [aiaInput]="controller" to your own