A configurable and customizable React chat component library
A configurable and customizable React chat component library built with TypeScript, Vite, and Tailwind CSS.
- ๐จ Fully Customizable - Configure themes, colors, positioning, and more
- ๐ฑ Responsive Design - Works seamlessly on desktop and mobile
- ๐ Streaming Support - Real-time streaming chat responses with OpenAI-compatible API
- โน๏ธ Stop Functionality - Stop streaming responses mid-process with dynamic button states
- ๐ Expandable Interface - Toggle between normal and full-screen width with expand/minimize button
- โฑ๏ธ Configurable Timeout - Set custom request timeout (default: 120 seconds)
- ๐ Rich Content - Supports markdown tables, links, and formatted text
- ๐ก Smart Suggestions - Interactive suggestion bubbles with custom icons that send messages directly
- ๐ Copy Functionality - Easy message copying with clipboard integration
- ๐พ Persistent Storage - Messages are automatically saved to localStorage
- ๐ฏ TypeScript - Full TypeScript support with comprehensive type definitions
- โก Lightweight - Minimal dependencies (Lucide React for icons, Framer Motion for animations)
- ๐งช Well Tested - Comprehensive visual and functional tests with Playwright
- ๐ญ Multiple Themes - Built-in themes (default, dark, green, pixie) with custom theme support
- ๐จ Live Theme Editor - Real-time theme customization in development with color pickers and export
- ๐ Error Handling - Automatic retry functionality with user-friendly error messages
- ๐ก๏ธ Input Validation - Built-in message sanitization and validation
- ๐ช Error Boundaries - Graceful error handling with React Error Boundaries
- ๐ค Bot Icons - Visual bot indicators on assistant messages for better UX
- ๐ Feedback System - Thumbs up/down feedback buttons with 5-star rating system and text input
- ๐ฌ Smooth Animations - Framer Motion powered animations for enhanced user experience
- ๐ค Lato Font - Modern typography with Google Fonts integration
- ๐ก Message Listener - Real-time message monitoring for consuming applications
- ๐จ CSS Modules - Scoped styling with CSS modules for better maintainability
- Node.js >= 20.0.0
- React >= 18.0.0
- React DOM >= 18.0.0
``bash`Install the package and required peer dependencies
npm install data-platform-chatbot lucide-react framer-motionor
yarn add data-platform-chatbot lucide-react framer-motionor
pnpm add data-platform-chatbot lucide-react framer-motion
> Why install peer dependencies separately? > lucide-react and framer-motion are peer dependencies to avoid version conflicts and duplicate installations. If you only install data-platform-chatbot, you'll get warnings and missing functionality. Installing all packages ensures compatibility and keeps your bundle size optimal.
The component uses CSS modules for styling. Simply import the CSS file:
`tsx`
import "data-platform-chatbot/dist/index.css";
The component includes Lato font from Google Fonts and all necessary styles are scoped using CSS modules to avoid conflicts with your application's styles.
IMPORTANT: The chat component requires a proxy configuration to work in development. Without this, chat requests will fail.
Add this to your vite.config.ts:
`typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
server: {
proxy: {
"/v1/chat/completions": {
target: env.VITE_PROXY_TARGET,
changeOrigin: true,
secure: false,
rewrite: (path) =>
path.replace(/^\/v1\/chat\/completions/, "/v1/chat/completions"),
},
},
},
});
`
Then use the proxy endpoint in your config:
`tsx`
endpoint: "/v1/chat/completions", // Use proxy path, not direct URL
// ... other config
}}
/>
`bashClone the repository
git clone
cd data-chatbot
Quick Start
`tsx
import React from "react";
import { ChatAssistant } from "data-platform-chatbot";
import "data-platform-chatbot/dist/index.css";function App() {
return (
My App
config={{
endpoint: "/v1/chat/completions", // Use proxy endpoint
title: "My Assistant",
theme: {
primary: "#3b82f6",
},
}}
/>
);
}
`Configuration
The
ChatAssistant component accepts a config prop with the following options:$3
`tsx
interface ChatConfig {
endpoint?: string; // API endpoint for chat
model?: string; // Model name to use
headers?: Record; // Custom headers
title?: string; // Chat window title
subtitle?: string; // Chat window subtitle
placeholder?: string; // Input placeholder text
position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
width?: number; // Chat window width
height?: number; // Chat window height
timeout?: number; // Request timeout in milliseconds (default: 120000)
defaultOpen?: boolean; // Open chat by default
onMessagesChange?: (messages: Message[]) => void; // Message listener callback
onFeedback?: (messageId: string, feedback: "agree" | "disagree", rating?: number, feedbackText?: string) => void; // Feedback callback
onClose?: () => void; // Chat close callback
}
`$3
`tsx
interface ChatTheme {
primary?: string; // Primary color
background?: string; // Background color
userMessageBg?: string; // User message background
assistantMessageBg?: string; // Assistant message background
borderColor?: string; // Border color
textColor?: string; // Text color
fabBg?: string; // FAB background color
fabColor?: string; // FAB icon color
}
`$3
Suggestions appear when the input field is focused and send messages directly when clicked (no need to press send):
`tsx
import {
Lightbulb,
HelpCircle,
MessageSquare,
ArrowLeftRight,
} from "lucide-react";const config = {
suggestions: [
{ icon: , text: "Explain this further" },
{ icon: , text: "Give me an example" },
{ icon: , text: "Possible follow-up questions" },
{ icon: , text: "Show me another options" },
],
};
`API Integration
The component expects your API endpoint to support streaming responses in the OpenAI format:
`typescript
// Request format
{
"model": "your-model",
"messages": [
{ "role": "user", "content": "Hello!" }
],
"stream": true
}// Response format (Server-Sent Events)
data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{"content":" there!"}}]}
data: [DONE]
`Development
$3
`bash
Development
npm run dev # Start development server with demo
npm run build # Build demo application
npm run build:lib # Build library for distribution
npm run preview # Preview built demoTesting
npm test # Run unit tests with Vitest
npm run test:ui # Run unit tests with UI
npm run test:clean # Clean test artifacts and cache
npm run test:e2e # Run end-to-end tests with Playwright
npm run test:e2e:ui # Run e2e tests with Playwright UI
npm run test:e2e:debug # Debug e2e tests
npm run test:visual # Run visual regression tests
npm run test:report # Show Playwright HTML test reportLinting
npm run lint # Lint code with ESLint
npm run lint:fix # Fix linting issuesPlaywright
npm run playwright:install # Install Playwright browsers
`$3
1. Start Development Server
`bash
npm run dev
` This starts the demo application at
http://localhost:51732. Use Live Theme Editor
- Click the palette icon in the top-right corner to open the theme editor
- Adjust colors in real-time with color pickers or hex inputs
- See changes instantly applied to the chat component
- Export your custom theme configuration to clipboard
- Reset to default theme anytime
3. Run Tests During Development
`bash
# Clean test artifacts before running
npm run test:clean # Run visual tests to see how components look
npm run test:visual
# Run functional tests to verify behavior
npm run test:e2e
# Debug tests interactively
npm run test:e2e:debug
# View test results in browser
npm run test:report
`4. Build Library
`bash
npm run build:lib
`
This creates the distributable library in the dist/ folder$3
This project includes comprehensive visual and functional testing:
- Visual Tests: Take screenshots and compare visual appearance
- Functional Tests: Test user interactions, API calls, and component behavior
- Cross-browser: Tests run on Chrome, Firefox, Safari, and mobile browsers
`bash
Clean test artifacts first
npm run test:cleanRun all tests
npm run test:e2eRun with UI for debugging
npm run test:e2e:uiRun only visual tests
npm run test:visualView test report in browser
npm run test:report
`$3
`
data-chatbot/
โโโ src/
โ โโโ lib/ # Library source code
โ โ โโโ components/ # React components
โ โ โโโ utils/ # Utility functions
โ โ โโโ types.ts # TypeScript definitions
โ โ โโโ index.ts # Main export
โ โโโ demo/ # Demo application
โ โ โโโ App.tsx # Demo app component
โ โ โโโ main.tsx # Demo entry point
โ โโโ styles/ # Global styles
โโโ tests/ # Playwright tests
โโโ scripts/ # Build and test scripts
โโโ dist/ # Built library (generated)
`Examples
$3
`tsx
import { ChatAssistant } from "data-platform-chatbot";
import "data-platform-chatbot/dist/index.css"; ;
`$3
`tsx
config={{
theme: {
primary: "#10b981",
userMessageBg: "#d1fae5",
assistantMessageBg: "#ecfdf5",
},
}}
/>
`$3
`tsx
config={{
theme: {
primary: "oklch(42.4% 0.199 265.638)",
userMessageBg: "#eaeaf8",
assistantMessageBg: "#EFF3F5",
borderColor: "#c1c1cd",
textColor: "#222222",
},
}}
/>
`$3
`tsx
config={{
position: "bottom-left",
width: 400,
height: 500,
}}
/>
`$3
`tsx
config={{
endpoint: "/v1/chat/completions", // Use proxy endpoint
model: "gpt-4",
headers: {
Authorization: "Bearer your-token",
"X-Custom-Header": "value",
},
}}
/>
`$3
Monitor chat messages in real-time for analytics, logging, or integration with other systems:
`tsx
const handleMessagesChange = (messages) => {
console.log('Chat messages updated:', messages);
// Send to analytics, save to database, etc.
}; config={{
onMessagesChange: handleMessagesChange,
// ... other config
}}
/>
// Or as direct prop
`$3
Capture user feedback with 5-star rating system and text input:
`tsx
const handleFeedback = (
messageId: string,
feedback: "agree" | "disagree",
rating?: number,
feedbackText?: string
) => {
console.log("Feedback received:", {
messageId,
feedback,
rating, // 1-5 stars (mandatory)
feedbackText, // Optional text feedback
timestamp: new Date().toISOString(),
});
// Send to your backend, analytics, etc.
}; config={{
onFeedback: handleFeedback,
// ... other config
}}
/>
`$3
Capture when user closes the chat:
`tsx
const handleClose = () => {
console.log("Chat closed at:", new Date().toISOString());
// Track analytics, save state, etc.
}; config={{
onClose: handleClose,
// ... other config
}}
/>
`$3
In development mode, use the live theme editor to create custom themes:
1. Open Theme Editor: Click the palette icon in the top-right corner
2. Adjust Colors: Use color pickers or enter hex values directly
3. See Changes Live: Watch the chat component update in real-time
4. Export Theme: Copy the generated theme configuration
5. Use in Production: Apply the exported theme to your component
`tsx
// Example exported theme from live editor
const customTheme = {
primary: "#ff6b6b",
background: "#ffffff",
userMessageBg: "#ffe3e3",
assistantMessageBg: "#f8f9fa",
borderColor: "#e9ecef",
textColor: "#212529",
fabBg: "#ffffff",
fabColor: "#ff6b6b",
}; ;
`Contributing
1. Fork the repository
2. Create a feature branch:
git checkout -b feature/new-feature
3. Make your changes
4. Run tests: npm run test:e2e
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request$3
- Follow the existing code style
- Add tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting PR
- Use semantic commit messages
Troubleshooting
$3
Playwright tests failing:
`bash
Reinstall browsers
npx playwright installUpdate Playwright
npm update @playwright/test
`Build issues:
`bash
Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
`TypeScript errors:
`bash
Check TypeScript configuration
npx tsc --noEmit
``MIT
For issues and questions:
- Create an issue in the repository
- Check existing documentation
- Review test files for usage examples