@buildlayer/ai-react
Version:
React UI components for AI chat assistants
854 lines (640 loc) • 21.5 kB
Markdown
# @buildlayer/ai-react
> Fully responsive React UI components for AI chat assistants with light/dark themes, mobile navigation, and full TypeScript support
[](https://www.npmjs.com/package/@buildlayer/ai-react)
[](https://opensource.org/licenses/MIT)
## Live Demo
**Try it now:** [ai-react.buildlayer.dev](https://ai-react.buildlayer.dev)
Experience the AI chat with pre-configured custom Local LLM support and all major provider options.
> Note: Some features are intentionally disabled in this demo version for performance and public access safety.
## Contents
- [Quick Setup with AI CLI](#quick-setup-with-ai-cli)
- [Manual Installation](#manual-installation)
- [Framework Support](#framework-support)
- [React (Client-Side)](#react-client-side)
- [Next.js (Server-Side Rendering)](#nextjs-server-side-rendering)
- [Adding to Existing React Apps](#adding-to-existing-react-apps)
- [Prerequisites](#prerequisites)
- [Fully Responsive](#fully-responsive)
- [Quick Start](#quick-start)
- [Screenshots](#screenshots)
- [Using Individual Components](#using-individual-components)
- [Provider Configuration](#provider-configuration)
- [Core Components](#core-components)
- [Hooks](#hooks)
- [Theme Support](#theme-support)
- [Styling](#styling)
- [TypeScript Support](#typescript-support)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Bug Reports & Feature Requests](#bug-reports--feature-requests)
- [What's Included (OSS)](#whats-included-oss)
- [What's Pro-Only](#whats-pro-only)
- [Framework-Specific Packages](#framework-specific-packages)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Quick Setup with AI CLI
The easiest way to get started is using our CLI tool:
```bash
# Create a new React AI chat app
npx @buildlayer/ai-cli create react my-ai-chat-app
# Or create a basic app
npx @buildlayer/ai-cli create basic my-ai-chat-app
# Navigate to your new project
cd my-ai-chat-app
# Install dependencies and start
npm install
npm start
```
This will create a complete React application with `@buildlayer/ai-react` pre-configured and ready to use!
## Manual Installation
If you prefer to add to an existing project:
```bash
# npm
npm install @buildlayer/ai-react
# pnpm
pnpm add @buildlayer/ai-react
# yarn
yarn add @buildlayer/ai-react
```
> **Note**: `@buildlayer/ai-core` is automatically included as a dependency and provides the AI chat engine and provider adapters.
## Framework Support
### React (Client-Side)
This package is designed for **React applications** and works perfectly with:
- Create React App
- Vite React
- React Router
- Any client-side React setup
### Next.js (Server-Side Rendering)
**Not supported** for Next.js due to server-side rendering conflicts. For Next.js support, use the dedicated `@buildlayer/ai-nextjs` (coming soon) package instead.
### Adding to Existing React Apps
You can easily integrate this package into existing React applications on specific routes:
```tsx
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import { App as AIApp } from '@buildlayer/ai-react';
function MyExistingApp() {
return (
<Router>
<Routes>
<Route path="/" element={<HomePage />} />
<Route path="/about" element={<AboutPage />} />
{/* Add AI chat on a specific route */}
<Route path="/ai-chat" element={<AIApp />} />
</Routes>
</Router>
);
}
```
## Prerequisites
Before installing, make sure you have:
- **React 18+** and **React DOM 18+**
- **React Router DOM 6+** (for the main `App` component)
- **Node.js 18+**
> **Pro Tip**: Use `npx @buildlayer/ai-cli create react my-app` to automatically set up all dependencies and configuration!
## Fully Responsive
The AI React components are fully responsive with mobile navigation, tablet support, and desktop optimization.
## Quick Start
```tsx
import React from 'react';
import { App } from '@buildlayer/ai-react';
function MyApp() {
return <App />;
}
export default MyApp;
```
## Screenshots
### Main Application
*Complete AI chat application with dark theme*
### Dark Theme
*Clean dark theme interface*
### Light Theme
*Modern light theme interface*
### Mobile Responsive Design
<!-- markdownlint-disable-next-line MD033 -->
<div align="center">
| Mobile Dark Theme | Mobile Light Theme |
|:---:|:---:|
|  |  |
| *Dark theme with hamburger navigation* | *Light theme with responsive layout* |
| Mobile Navigation Dark | Mobile Navigation Light |
|:---:|:---:|
|  |  |
| *Mobile navigation panel with dark theme* | *Mobile navigation panel with light theme* |
</div>
### Using Individual Components
```tsx
import React from 'react';
import { ChatPanel, useChat, ThemeProvider } from '@buildlayer/ai-react';
import { createOpenAIAdapter, ChatStore } from '@buildlayer/ai-core';
function CustomApp() {
const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!);
const chatController = new ChatStore(adapter);
return (
<ThemeProvider defaultTheme="dark">
<div className="h-screen">
<ChatPanel chatController={chatController} />
</div>
</ThemeProvider>
);
}
export default CustomApp;
```
## Provider Configuration
### Supported AI Providers
The package works with multiple AI providers through `@buildlayer/ai-core`:
#### OpenAI
```tsx
import { createOpenAIAdapter, ChatStore } from '@buildlayer/ai-core';
const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!);
const chatController = new ChatStore(adapter);
```
#### Anthropic
```tsx
import { createAnthropicAdapter, ChatStore } from '@buildlayer/ai-core';
const adapter = createAnthropicAdapter(process.env.ANTHROPIC_API_KEY!);
const chatController = new ChatStore(adapter);
```
#### Mistral
```tsx
import { createMistralAdapter, ChatStore } from '@buildlayer/ai-core';
const adapter = createMistralAdapter(process.env.MISTRAL_API_KEY!);
const chatController = new ChatStore(adapter);
```
#### Grok
```tsx
import { createGrokAdapter, ChatStore } from '@buildlayer/ai-core';
const adapter = createGrokAdapter(process.env.GROK_API_KEY!);
const chatController = new ChatStore(adapter);
```
#### Local LLM (Ollama)
```tsx
import { createLocalLLMAdapter, ChatStore } from '@buildlayer/ai-core';
const adapter = createLocalLLMAdapter({
baseURL: "http://localhost:11434/v1", // Ollama default
model: "",
apiKey: "ollama", // Optional
});
const chatController = new ChatStore(adapter);
```
#### Custom Provider URL
```tsx
// For custom OpenAI-compatible endpoints
const adapter = createOpenAIAdapter(apiKey, {
baseURL: "https://your-custom-endpoint.com/v1"
});
const chatController = new ChatStore(adapter);
```
## Core Components
### App
The main application component:
*Complete application with basic chat functionality*
```tsx
import { App } from '@buildlayer/ai-react';
function MyApp() {
return <App />;
}
```
> **Note**: The `App` component requires `react-router-dom` as a peer dependency and includes routing, state management, and a welcome screen when not connected to an AI provider.
### ChatPanel
The main chat interface component:
*Main chat interface with message history and input*
```tsx
import { ChatPanel } from '@buildlayer/ai-react';
import { createOpenAIAdapter, ChatStore } from '@buildlayer/ai-core';
function MyChatApp() {
const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!);
const chatController = new ChatStore(adapter);
return (
<ChatPanel
chatController={chatController}
model="gpt-4"
className="max-w-4xl mx-auto"
/>
);
}
```
### MessageList
Display chat messages:
*Message display with conversation history*
```tsx
import { MessageList } from '@buildlayer/ai-react';
function ChatMessages({ chatController }) {
return (
<MessageList
chatController={chatController}
className="flex-1 overflow-y-auto"
/>
);
}
```
### Composer
Message input component:
*Message input with send button and model selection*
```tsx
import { Composer } from '@buildlayer/ai-react';
function MessageInput({ chatController }) {
return (
<Composer
chatController={chatController}
model="gpt-4"
placeholder="Type your message..."
/>
);
}
```
### ChatHeader
Chat header with session information:
*Header with session info and clear history button*
```tsx
import { ChatHeader } from '@buildlayer/ai-react';
function ChatHeaderComponent({ chatController }) {
return (
<ChatHeader
chatController={chatController}
onClearHistory={() => chatController.clearHistory()}
/>
);
}
```
### ThemeSwitcher
Theme toggle component:
*Theme toggle button for switching between light and dark modes*
```tsx
import { ThemeSwitcher } from '@buildlayer/ai-react';
function Header() {
return (
<header className="flex justify-between items-center p-4">
<h1>AI Assistant</h1>
<ThemeSwitcher />
</header>
);
}
```
## Hooks
### useChat
Basic chat functionality:
```tsx
import { useChat } from '@buildlayer/ai-react';
import { createOpenAIAdapter, ChatStore } from '@buildlayer/ai-core';
function ChatComponent() {
const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!);
const chatController = new ChatStore(adapter);
const chat = useChat(chatController);
const handleSend = async (message: string) => {
await chat.send(message);
};
return (
<div>
<div>
{chat.messages.map((msg) => (
<div key={msg.id}>{msg.content[0]?.text}</div>
))}
</div>
<button onClick={() => handleSend("Hello!")}>
Send Message
</button>
</div>
);
}
```
### useChatWithSingleSession
Single session management with persistence (OSS version):
```tsx
import { useChatWithSingleSession } from '@buildlayer/ai-react';
import { createOpenAIAdapter, ChatStore } from '@buildlayer/ai-core';
function ChatWithPersistence() {
const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!);
const chatController = new ChatStore(adapter);
const { session, clearSession, exportSession } = useChatWithSingleSession(chatController);
return (
<div>
<div>Session: {session?.name}</div>
<button onClick={clearSession}>Clear Session</button>
<button onClick={() => console.log(exportSession())}>Export</button>
</div>
);
}
```
> **Note**: This is the OSS version with single session support. For multi-session management, use `@buildlayer/ai-react-pro` with `useSessionManager`.
### useApp
Application state management:
```tsx
import { useApp } from '@buildlayer/ai-react';
function AppComponent() {
const { state, connect, disconnect } = useApp();
return (
<div>
<div>Connected: {state.isConnected ? 'Yes' : 'No'}</div>
<div>Provider: {state.selectedProvider.name}</div>
<div>Model: {state.selectedModel}</div>
</div>
);
}
```
## Theme Support
### Theme Comparison
*Clean and minimal dark theme*
*Modern and sleek light theme*
### ThemeProvider
Wrap your app with theme provider:
```tsx
import { ThemeProvider, useTheme } from '@buildlayer/ai-react';
function ThemedApp() {
return (
<ThemeProvider defaultTheme="dark">
<MyChatApp />
</ThemeProvider>
);
}
```
### useTheme Hook
Access theme state in your components:
```tsx
import { useTheme, useThemeAwareStyle } from '@buildlayer/ai-react';
function Header() {
const { theme, setTheme } = useTheme();
const { isDark, isLight } = useThemeAwareStyle();
return (
<header className="flex justify-between items-center p-4">
<h1>AI Assistant</h1>
<button
onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
className="px-3 py-1 text-sm"
>
{theme === 'dark' ? '☀️' : '🌙'}
</button>
<div>Is Dark: {isDark.toString()}</div>
</header>
);
}
```
## Styling
### Tailwind CSS
The components are built with Tailwind CSS. Make sure to include Tailwind in your project:
```bash
npm install -D tailwindcss
npx tailwindcss init
```
Add to your `tailwind.config.js`:
```js
module.exports = {
content: [
"./src/**/*.{js,ts,jsx,tsx}",
"./node_modules/@buildlayer/ai-react/**/*.{js,ts,jsx,tsx}"
],
theme: {
extend: {},
},
plugins: [],
}
```
### Theme Classes
The package includes built-in light and dark theme classes:
- `light-theme` - Light theme styling
- `dark-theme` - Dark theme styling
Themes are automatically applied based on the `data-theme` attribute on the HTML element.
### Custom Styling
You can customize the appearance using CSS classes:
```tsx
<ChatPanel
chatController={chat}
className="bg-white dark:bg-gray-900 rounded-lg shadow-lg"
/>
```
## TypeScript Support
All components are fully typed:
```tsx
import type {
ChatPanelProps,
MessageListProps,
ComposerProps,
ChatHeaderProps,
ThemeSwitcherProps,
AppProps,
AppRoutesProps,
NavigationProps,
Theme,
ThemeConfig,
ThemeContextType,
ThemeProviderProps,
AppState,
AppContextType,
AppProviderProps,
SingleChatSession
} from '@buildlayer/ai-react';
interface MyChatProps extends ChatPanelProps {
customProp?: string;
}
```
## API Reference
### Components
#### ChatPanelProps
```tsx
interface ChatPanelProps {
chatController: ChatController;
model?: string;
className?: string;
}
```
#### MessageListProps
```tsx
interface MessageListProps {
chatController: ChatController;
className?: string;
}
```
#### ComposerProps
```tsx
interface ComposerProps {
chatController: ChatController;
model?: string;
className?: string;
placeholder?: string;
disabled?: boolean;
disabledReasons?: string[];
}
```
#### ChatHeaderProps
```tsx
interface ChatHeaderProps {
chatController: ChatController;
onClearHistory: () => void;
className?: string;
}
```
#### AppProps
```tsx
interface AppProps {
className?: string;
}
```
### Hook APIs
#### useChat API
```tsx
function useChat(chatController: ChatController): {
sessionId: string;
messages: Message[];
status: ChatStatus;
error: string | null;
send: (input: string | ContentPart[], opts?: SendOpts) => Promise<void>;
stop: () => void;
reset: () => void;
importHistory: (msgs: Message[]) => void;
exportHistory: () => Message[];
clearHistory: () => void;
};
```
#### useChatWithSingleSession API
```tsx
function useChatWithSingleSession(chatController: ChatController): {
session: SingleChatSession | null;
isLoaded: boolean;
clearSession: () => void;
exportSession: () => ExportData | null;
};
```
#### useTheme API
```tsx
function useTheme(): {
theme: 'light' | 'dark';
setTheme: (theme: 'light' | 'dark') => void;
};
function useThemeAwareStyle(): {
isDark: boolean;
isLight: boolean;
};
```
#### useApp API
```tsx
function useApp(): {
state: AppState;
connect: (config: ProviderConfig) => Promise<void>;
connectLegacy: (provider: string, model: string, apiKey?: string) => Promise<void>;
disconnect: () => void;
clearError: () => void;
loadAvailableProviders: () => Promise<void>;
loadAvailableModels: (provider: string) => Promise<void>;
};
```
## Examples
### Basic Chat App
```tsx
import React from 'react';
import { App } from '@buildlayer/ai-react';
function BasicChat() {
return <App />;
}
```
### Custom Chat App
```tsx
import React from 'react';
import { ChatPanel, ThemeProvider } from '@buildlayer/ai-react';
import { createOpenAIAdapter, ChatStore } from '@buildlayer/ai-core';
function CustomChat() {
const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!);
const chatController = new ChatStore(adapter);
return (
<ThemeProvider defaultTheme="dark">
<div className="h-screen flex flex-col">
<ChatPanel chatController={chatController} model="gpt-4" />
</div>
</ThemeProvider>
);
}
```
### Custom Theme App
```tsx
import React from 'react';
import { ChatPanel, ThemeProvider, useTheme, ThemeSwitcher } from '@buildlayer/ai-react';
import { createOpenAIAdapter, ChatStore } from '@buildlayer/ai-core';
function CustomThemedApp() {
const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!);
const chatController = new ChatStore(adapter);
return (
<ThemeProvider defaultTheme="dark">
<div className="h-screen flex flex-col">
<Header />
<ChatPanel chatController={chatController} model="gpt-4" />
</div>
</ThemeProvider>
);
}
function Header() {
const { theme, setTheme } = useTheme();
return (
<header className="flex justify-between items-center p-4 border-b">
<h1>My AI Assistant</h1>
<div className="flex items-center gap-2">
<ThemeSwitcher />
<button
onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
className="px-3 py-1 text-sm rounded"
>
{theme === 'dark' ? 'Light' : 'Dark'}
</button>
</div>
</header>
);
}
```
## Bug Reports & Feature Requests
Found a bug or have a feature request? We'd love to hear from you!
- **Bug Reports**: [Open an issue](https://github.com/BuildLayer/ai-react/issues/new?template=bug_report.md)
- **Feature Requests**: [Open an issue](https://github.com/BuildLayer/ai-react/issues/new?template=feature_request.md)
- **General Discussion**: [GitHub Discussions](https://github.com/BuildLayer/ai-react/discussions)
### What's Included (OSS)
This package includes basic chat UI components:
- ✅ `App` - Complete application component
- ✅ `AppRoutes` - Routing component
- ✅ `Navigation` - Navigation component
- ✅ `ChatPanel` - Main chat interface
- ✅ `MessageList` - Message display
- ✅ `Composer` - Message input
- ✅ `ChatHeader` - Chat header with session info
- ✅ `ThemeSwitcher` - Theme toggle component
- ✅ `LoadingSpinner` - Loading indicator
- ✅ `useChat` - Basic chat hook
- ✅ `useChatWithSingleSession` - Single session with persistence (OSS)
- ✅ `useApp` - Application state management
- ✅ `ThemeProvider` - Light/dark themes
- ✅ `useTheme` - Theme management
- ✅ `useThemeAwareStyle` - Theme-aware styling
- ✅ `AppProvider` - Application context provider
### What's Pro-Only
Advanced features are available in `@buildlayer/ai-react-pro` (coming soon):
- 🔒 Tool calling forms and UI
- 🔒 Advanced themes (nebula, plasma, synthwave)
- 🔒 Multi-session management (`useSessionManager`) - manage multiple chat sessions
- 🔒 Advanced UX components
- 🔒 Export/import functionality
- 🔒 Advanced persistence adapters
- 🔒 `runTool` functionality in `useChat`
- 🔒 `currentToolCall` in chat state
> **Note**: Pro-only features will be available in the separate `@buildlayer/ai-react-pro` package.
### Framework-Specific Packages
- **React (Client-Side)**: `@buildlayer/ai-react` ← You are here
- **Next.js (SSR)**: `@buildlayer/ai-nextjs` (coming soon)
- **Vue.js**: `@buildlayer/ai-vue` (coming soon)
- **Svelte**: `@buildlayer/ai-svelte` (coming soon)
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- [React](https://reactjs.org/) - UI library
- [Tailwind CSS](https://tailwindcss.com/) - CSS framework
- [TypeScript](https://www.typescriptlang.org/) - Type safety
- [@buildlayer/ai-core](https://www.npmjs.com/package/@buildlayer/ai-core) - AI chat engine
- [@buildlayer/ai-cli](https://www.npmjs.com/package/@buildlayer/ai-cli) - CLI tool for project setup
## Made with ❤️ by the BuildLayer.dev team
For advanced features like tool calling, session persistence, and premium themes, check out [@buildlayer/ai-react-pro](https://www.npmjs.com/package/@buildlayer/ai-react-pro) (coming soon).
For Next.js support, use [@buildlayer/ai-nextjs](https://www.npmjs.com/package/@buildlayer/ai-nextjs) (coming soon).