Interface modules

The interface modules are the AI features a site adds in a few lines, with no interface to build. Each one runs the conversation on the visitor's own AI through AI Wallet, calls your site's tools from your MCP server, and draws the whole exchange.

The React components come with @aiconnect/react. The Web Components are the same modules in one script for sites without React, such as WordPress pages: see Web Components.

What every module doesCopy Anchor Link

• Streams the answer. The text appears as the visitor's model writes it, with a cyan caret at its end. Light Markdown (bold, lists, links, code) is drawn as formatting.
• Shows the tool calls as they run. Each call of one of your tools gets a row with a cyan light while it runs, a check once its result is back, and the arguments the model chose.
• Names the account that answers. The header shows the account and its model as the wallet reports them (state.providerName and state.model), with the wallet's arcs lit while the answer streams.
• Handles the connect and install steps. Until the visitor's AI is connected, the module shows the step the visitor is at: connect the wallet, add it to the browser, approve the site, or try again after a refusal. Its button opens the connect window. A question asked before the connection stays on screen and goes out once the wallet connects the site.
• Offers Stop. While an answer streams, the send button becomes Stop. Stopping ends the answer in the wallet too and keeps the text written so far.
• Follows your design system. Every color, the font, the radii and the sizes come from the --aic-* tokens, in light, dark and right to left. See Theming the modules.
• Speaks English, French and Hebrew. The provider's locale sets the language of the modules and of the connect window. Hebrew lays the module out right to left, and the side panel and the popup move to the left edge.

QuickstartCopy Anchor Link

Install the packages and wrap your app in AiConnectProvider, as in the React quickstart. The stylesheet @aiconnect/react/styles.css carries the modules' styles with the connect window's.

npm install @aiconnect/core @aiconnect/react

Then render a module where it belongs. This popup answers from the tools of your MCP server:

import { AiChatPopup } from '@aiconnect/react';

const SYSTEM = 'You recommend books from this site\'s catalog. Always search the catalog before recommending.';

export function App() {
  return (
    <>
      <YourSite />
      <AiChatPopup system={SYSTEM} mcp="/api/mcp" suggestions={['A calm book for tonight']} />
    </>
  );
}

import { AiConnect } from '@aiconnect/core';
import { AiConnectProvider } from '@aiconnect/react';
import '@aiconnect/react/styles.css';

const client = new AiConnect();

createRoot(document.getElementById('root')!).render(
  <AiConnectProvider client={client} locale="en">
    <App />
  </AiConnectProvider>,
);

The module needs nothing else: the visitor clicks the floating button, connects their AI from the popup the first time, and asks. A visitor who does not have the wallet yet gets a link to the AI Wallet page.

In a Next.js App Router site, render the modules from a client component inside your provider, as the Next.js quickstart does for the provider itself.

Props every module takesCopy Anchor Link

• system. The instructions the visitor's model gets before the first question: what the site is, which tools to use and how to answer.
• tools and mcp. Where your tools come from. Give one of them. Keep a tools object stable across renders, for example by building it once outside the component.
• title, intro and placeholder. Your own words for the header, for the heading of an empty conversation, and for the question box. Without them the module uses its built in copy in the provider's language.
• suggestions. Questions shown in an empty conversation, sent with one click.
• toolLabels. A plain name per tool, shown while it runs, such as { search_books: 'Searching the catalog' }. Without one, the row shows the tool's own name.
• renderToolResults. Draws a turn's tool results your way. See Your own result cards.

The side panel, the popup and the full page also take how they open:

Leave open out to let the module keep its state. Give open and onOpenChange to open it from your own button, and hideLauncher to hide the module's own.

Your own result cardsCopy Anchor Link

renderToolResults receives each turn, with the visitor's question, the answer so far and every tool call with its raw result, and returns what to draw under the answer. It runs again as the answer streams, so cards can follow the names the answer gives.

Taamtaam draws the restaurants its catalog search returned that the answer names, in the order the answer names them:

import type { ChatTurn } from '@aiconnect/react';

function renderRestaurants(turn: ChatTurn) {
  const restaurants = suggestedRestaurants(turn);
  if (restaurants.length === 0) {
    return null;
  }
  return (
    <ul className={styles.suggestions}>
      {restaurants.map((restaurant) => <li key={restaurant.id}><RestaurantCard restaurant={restaurant} /></li>)}
    </ul>
  );
}

<AiChatPanel system={SYSTEM_PROMPT} mcp="/api/mcp" renderToolResults={renderRestaurants} />;

The cards render inside the module, so your own stylesheet styles them.

LanguagesCopy Anchor Link

AiConnectProvider takes locale (en, fr or he) for the connect window and the modules together. The modules' built in copy is builtInModuleMessages. Pass moduleMessages to the provider to write the whole copy yourself, and set its dir to rtl for a right to left language.

The modules also show the connect window's own copy for the connection steps, from messages.

Theming the modulesCopy Anchor Link

The modules read the tokens of the theming guide and these ones of their own:

--aic-fill and --aic-ink-2 are mixed from your --aic-ink and --aic-surface when you do not set them, so a site that sets its own palette gets matching shades. Dark mode follows data-aic-theme, as for the connect window.

Taamtaam's theme sets its font, its warm palette and a wider panel:

:root {
  --aic-font: var(--font-montserrat), sans-serif;
  --aic-ink: #2f2b22;
  --aic-muted: #5c5544;
  --aic-ground: #f7f5f0;
  --aic-border: #e2ddd1;
  --aic-accent: #6f6754;
  --aic-panel-width: 440px;
}

Next stepsCopy Anchor Link

• Pick a form: side panel, popup, inline chat, full page or search bar.
• Add the modules to a page without React with one script tag.
• Serve your tools with the MCP guide.