@buildlayer/ai-react

Fully responsive React UI components for AI chat assistants with light/dark themes, mobile navigation, and full TypeScript support

Live Demo

Try it now: 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
• Manual Installation
• Framework Support
  • React (Client-Side)
  • Next.js (Server-Side Rendering)
  • Adding to Existing React Apps
• Prerequisites
• Fully Responsive
• Quick Start
• Screenshots
• Using Individual Components
• Provider Configuration
• Core Components
• Hooks
• Theme Support
• Styling
• TypeScript Support
• API Reference
• Examples
• Bug Reports & Feature Requests
• What's Included (OSS)
• What's Pro-Only
• Framework-Specific Packages
• License
• Acknowledgments

Quick Setup with AI CLI

The easiest way to get started is using our CLI tool:

# 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:

# 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:

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

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

| 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 |

Using Individual Components

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

import { createOpenAIAdapter, ChatStore } from '@buildlayer/ai-core';

const adapter = createOpenAIAdapter(process.env.OPENAI_API_KEY!);
const chatController = new ChatStore(adapter);

Anthropic

import { createAnthropicAdapter, ChatStore } from '@buildlayer/ai-core';

const adapter = createAnthropicAdapter(process.env.ANTHROPIC_API_KEY!);
const chatController = new ChatStore(adapter);

Mistral

import { createMistralAdapter, ChatStore } from '@buildlayer/ai-core';

const adapter = createMistralAdapter(process.env.MISTRAL_API_KEY!);
const chatController = new ChatStore(adapter);

Grok

import { createGrokAdapter, ChatStore } from '@buildlayer/ai-core';

const adapter = createGrokAdapter(process.env.GROK_API_KEY!);
const chatController = new ChatStore(adapter);

Local LLM (Ollama)

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

// 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

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

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

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

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

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

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:

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):

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:

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:

import { ThemeProvider, useTheme } from '@buildlayer/ai-react';

function ThemedApp() {
  return (
    <ThemeProvider defaultTheme="dark">
      <MyChatApp />
    </ThemeProvider>
  );
}

useTheme Hook

Access theme state in your components:

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:

npm install -D tailwindcss
npx tailwindcss init

Add to your tailwind.config.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:

<ChatPanel 
  chatController={chat}
  className="bg-white dark:bg-gray-900 rounded-lg shadow-lg"
/>

TypeScript Support

All components are fully typed:

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

interface ChatPanelProps {
  chatController: ChatController;
  model?: string;
  className?: string;
}

MessageListProps

interface MessageListProps {
  chatController: ChatController;
  className?: string;
}

ComposerProps

interface ComposerProps {
  chatController: ChatController;
  model?: string;
  className?: string;
  placeholder?: string;
  disabled?: boolean;
  disabledReasons?: string[];
}

ChatHeaderProps

interface ChatHeaderProps {
  chatController: ChatController;
  onClearHistory: () => void;
  className?: string;
}

AppProps

interface AppProps {
  className?: string;
}

Hook APIs

useChat API

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

function useChatWithSingleSession(chatController: ChatController): {
  session: SingleChatSession | null;
  isLoaded: boolean;
  clearSession: () => void;
  exportSession: () => ExportData | null;
};

useTheme API

function useTheme(): {
  theme: 'light' | 'dark';
  setTheme: (theme: 'light' | 'dark') => void;
};

function useThemeAwareStyle(): {
  isDark: boolean;
  isLight: boolean;
};

useApp API

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

import React from 'react';
import { App } from '@buildlayer/ai-react';

function BasicChat() {
  return <App />;
}

Custom Chat App

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

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
• Feature Requests: Open an issue
• General Discussion: GitHub 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 file for details.

Acknowledgments

• React - UI library
• Tailwind CSS - CSS framework
• TypeScript - Type safety
• @buildlayer/ai-core - AI chat engine
• @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 (coming soon).

For Next.js support, use @buildlayer/ai-nextjs (coming soon).