How to add AI Autocomplete to React in 10 minutes

1. Install the React package

From the application directory, add the React SDK. It expects React and React DOM as peer dependencies, which an existing React application already has.

The package is @magicx-eng/ai-autocomplete-react. The command below uses pnpm; npm, Yarn, or Bun can install the same package with their normal add command.

• pnpm: pnpm add @magicx-eng/ai-autocomplete-react
• npm: npm install @magicx-eng/ai-autocomplete-react
• Yarn: yarn add @magicx-eng/ai-autocomplete-react
• Bun: bun add @magicx-eng/ai-autocomplete-react

No separate stylesheet import is required. The SDK ships its base styles, and the component accepts a class name and CSS variables when the interface needs to match the host application.

pnpm add @magicx-eng/ai-autocomplete-react

2. Render the component and handle submit

Import AIAutocomplete and place it where the current input belongs. The public key goes into apiConfig. The placeholder introduces the kind of request the product handles.

The onSubmit callback receives the completed result. Use result.query when the downstream system wants readable text. Use result.completed_params when the application also needs the selected fields.

The SDK completes the request. Your application still owns search, navigation, submission, or the action that follows.

In the example below, the existing search function receives the completed query. Replace it with the call your product already makes: update a router query, call Algolia, submit a form, send a chat message, or start an agent task.

import { AIAutocomplete } from "@magicx-eng/ai-autocomplete-react";

export function App() {
  return (
    <AIAutocomplete
      apiConfig={{ apiKey: import.meta.env.VITE_MAGICX_PUBLIC_KEY }}
      placeholder="Find something"
      onSubmit={(result) => 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 includes the server and browser code.

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 covers styling, controlled state, runtime options, and the full API reference.