React UI toolkit, hooks, and adapters for building AIPex-powered chat experiences
npm install @aipexstudio/aipex-reactReact UI toolkit for building AIPex-powered chat and extension experiences.
This package depends on @aipexstudio/aipex-core only (no browser-specific runtime code). It provides:
- Chat UI: and related components, slots, and themes
- Headless primitives: useChat, ChatAdapter (convert core AgentEvent streams into UI messages)
- Settings UI + persistence: , useChatConfig (storage via KeyValueStorage)
- Extension building blocks: , , intervention cards, fake mouse cursor
- Optional submodules: i18n provider and theme provider (via package subpath exports)
- Core-first: UI consumes AgentEvent from @aipexstudio/aipex-core and does not assume a runtime.
- Storage abstraction: persistence is done through KeyValueStorage (localStorage by default; can be
swapped for chrome.storage, IndexedDB, etc).
- Streaming UX: the adapter + hooks are built around incremental updates and tool lifecycle states.
- Customization: compose your UI with component overrides and slots, and style via CSS variables.
``bash`
npm install @aipexstudio/aipex-react @aipexstudio/aipex-coreor
pnpm add @aipexstudio/aipex-react @aipexstudio/aipex-core
Peer dependencies:
- reactreact-dom
-
`tsx
import { google } from "@ai-sdk/google";
import { AIPex, aisdk } from "@aipexstudio/aipex-core";
import { Chatbot } from "@aipexstudio/aipex-react";
const agent = AIPex.create({
instructions: "You are a helpful assistant.",
model: aisdk(google("gemini-2.5-flash")),
});
export function App() {
return
}
`
useChat is a rendering-free hook for building your own UI.
`tsx
import { useChat } from "@aipexstudio/aipex-react";
export function MyChat({ agent }: { agent: any }) {
const { messages, status, sendMessage, interrupt, reset, regenerate } = useChat(agent);
return (
{JSON.stringify(messages, null, 2)}$3
The Chatbot uses CSS variables to keep theming predictable and framework-friendly.
Built-in themes:
-
defaultTheme
- darkTheme
- minimalTheme
- colorfulThemeYou can also build your own theme:
`tsx
import { Chatbot, createTheme } from "@aipexstudio/aipex-react";const myTheme = createTheme({
className: "my-chat",
variables: {
"--chatbot-primary": "hsl(262 83% 58%)",
"--chatbot-radius": "12px",
},
});
export function App({ agent }: { agent: any }) {
return ;
}
`$3
Chatbot supports:- Component overrides (replace structural components)
- Slots (inject custom UI fragments like tool display, message actions, etc.)
`tsx
import { Chatbot } from "@aipexstudio/aipex-react";export function App({ agent }: { agent: any }) {
return (
agent={agent}
slots={{
messageActions: ({ message }) => ,
}}
/>
);
}
`$3
useChatConfig loads/saves AppSettings using a KeyValueStorage adapter.- Default storage: localStorage-backed adapter
- Extension storage: pass any
KeyValueStorage (e.g. ChromeStorageAdapter from @aipexstudio/browser-runtime)`tsx
import { SettingsPage } from "@aipexstudio/aipex-react";
import { chromeStorageAdapter } from "@aipexstudio/browser-runtime";export function Options() {
return ;
}
`$3
This package exposes i18n + theme contexts via subpath exports:
-
@aipexstudio/aipex-react/i18n/context
- @aipexstudio/aipex-react/theme/context`tsx
import { ChromeStorageAdapter } from "@aipexstudio/browser-runtime";
import { I18nProvider } from "@aipexstudio/aipex-react/i18n/context";
import { ThemeProvider } from "@aipexstudio/aipex-react/theme/context";
import type { Language } from "@aipexstudio/aipex-react/i18n/types";
import type { Theme } from "@aipexstudio/aipex-react/theme/types";
import { Chatbot } from "@aipexstudio/aipex-react";const i18nStorage = new ChromeStorageAdapter();
const themeStorage = new ChromeStorageAdapter();
export function App({ agent }: { agent: any }) {
return (
);
}
`$3
ContentScript is an extensible component for browser extension content scripts. It:- mounts an Omni-like UI (default or custom)
- hosts plugins with a shared state + event bus
- integrates with
chrome.runtime-like message passing (when available)`tsx
import { ContentScript, type ContentScriptPlugin } from "@aipexstudio/aipex-react";const loggerPlugin: ContentScriptPlugin = {
name: "logger",
setup: (ctx) => {
ctx.state.loggerReady = true;
},
onMessage: async (message, ctx) => {
console.log("[content-script message]", message);
ctx.emit("debug:message", message);
},
onEvent: (event, data) => {
if (event === "debug:message") {
console.log("[content-script event]", data);
}
},
};
export function InjectedUI() {
return ;
}
`API reference
$3
-
Chatbot(props)
- agent: AIPex | undefined
- config?: ChatConfig
- handlers?: ChatbotEventHandlers
- components?: ChatbotComponents
- slots?: ChatbotSlots
- theme?: ChatbotTheme
- className?: string
- initialSettings?: Partial
- storageAdapter?: KeyValueStorage (defaults to localStorage)
- models?: Array<{ name: string; value: string }>
- placeholderTexts?: string[]
- title?: string-
ChatbotProvider(props) is the same core provider but expects children and does not include title/models.$3
Customize specific parts of the Chatbot UI:
-
messageActions(props)
- inputToolbar(props)
- modelSelector(props)
- contextTags(props)
- toolDisplay(props)
- headerContent()
- footerContent()
- emptyState(props)
- loadingIndicator()
- afterMessages()$3
-
useChat(agent, options?) → { messages, status, sessionId, sendMessage, continueConversation, interrupt, reset, regenerate, setMessages }
- useChatConfig(options?) → { settings, isLoading, updateSetting, updateSettings, resetSettings, reloadSettings }
- ChatAdapter / createChatAdapter(options?)$3
-
SettingsPage(props)
- storageAdapter: KeyValueStorage
- storageKey?: string
- className?: string
- onSave?: (settings: AppSettings) => void
- onTestConnection?: (settings: AppSettings) => Promise$3
- Presets:
defaultTheme, darkTheme, minimalTheme, colorfulTheme
- Variables: defaultThemeVariables, darkThemeVariables
- Helpers: createTheme(overrides), mergeThemes(base, overrides)$3
Import from
@aipexstudio/aipex-react/i18n/context:-
I18nProvider({ storageAdapter, children })
- useTranslation() → { language, t(key, params?), changeLanguage }$3
Import from
@aipexstudio/aipex-react/theme/context:-
ThemeProvider({ storageAdapter, scope?, children })
- useTheme() → { theme, effectiveTheme, changeTheme }$3
-
ContentScript(props)
- initialOpen?: boolean
- onOpen?: () => void
- onClose?: () => void
- plugins?: ContentScriptPlugin[]
- messageHandlers?: MessageHandlers
- runtime?: RuntimeApi (defaults to chrome.runtime-like global if available)
- container?: HTMLElement
- shadowRoot?: ShadowRoot
- initContentScript(props, options?) → cleanup functionBuilt-in runtime message actions handled by
ContentScript:-
message.action === "aipex_open_omni"
- message.action === "aipex_close_omni"$3
-
Omni (command palette)
- FakeMouse (+ controller/types)
- Intervention components: InterventionCard, SelectionCard, MonitorCard, VoiceCard, InterventionModeToggleDevelopment (monorepo)
From the repository root:
`bash
pnpm --filter @aipexstudio/aipex-react build
pnpm --filter @aipexstudio/aipex-react typecheck
pnpm --filter @aipexstudio/aipex-react test
``MIT