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

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

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
.storybook		.storybook
screenshots		screenshots
src		src
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

License

BuildLayer/ai-react

Folders and files

Latest commit

History

Repository files navigation

@buildlayer/ai-react

Live Demo

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

Main Application

Dark Theme

Light Theme

Mobile Responsive Design

Using Individual Components

Provider Configuration

Supported AI Providers

OpenAI

Anthropic

Mistral

Grok

Local LLM (Ollama)

Custom Provider URL

Core Components

App

ChatPanel

MessageList

Composer

ChatHeader

ThemeSwitcher

Hooks

useChat

useChatWithSingleSession

useApp

Theme Support

Theme Comparison

ThemeProvider

useTheme Hook

Styling

Tailwind CSS

Theme Classes

Custom Styling

TypeScript Support

API Reference

Components

ChatPanelProps

MessageListProps

ComposerProps

ChatHeaderProps

AppProps

Hook APIs

useChat API

useChatWithSingleSession API

useTheme API

useApp API

Examples

Basic Chat App

Custom Chat App

Custom Theme App

Bug Reports & Feature Requests

What's Included (OSS)

What's Pro-Only

Framework-Specific Packages

License

Acknowledgments

Made with ❤️ by the BuildLayer.dev team

About

Topics

Resources

License

Code of conduct

Packages