acecoderz-chat-ui

A framework-agnostic, fully customizable chat UI package that works with React, Solid, Vanilla JS, and any other framework.

Features

• 🎨 Fully Customizable - Theme via CSS variables or props
• 🔌 Framework Agnostic - Works with React, Solid, Vue, Svelte, and Vanilla JS
• 🚀 Lightweight Core - Zero framework dependencies in the core
• 💬 Real-time Support - WebSocket and HTTP API support
• 🎯 TypeScript - Full TypeScript support
• 📦 Modular - Import only what you need
• ✅ Package Manager Compatible - Works with both npm and pnpm
• 💾 Message Persistence - Automatic localStorage save/restore
• ✂️ Message Actions - Copy, delete, and edit messages
• ♿ Accessible - Full ARIA support and keyboard navigation
• 🎭 Improved Loading - Animated indicators with accessibility

Installation

npm

npm install acecoderz-chat-ui

pnpm

pnpm add acecoderz-chat-ui

yarn

yarn add acecoderz-chat-ui

Note: This package is compatible with npm, pnpm, and yarn. Use the package manager your project uses.

Browser / CDN (Script Tag)

For browser usage without a build step, see CDN.md for detailed documentation.

Quick Start:

<!-- Include CSS -->
<link rel="stylesheet" href="https://cdn.example.com/chatbot-ui.css">

<!-- Include JavaScript -->
<script src="https://cdn.example.com/chatbot-ui.min.js"></script>

<!-- Add container -->
<div id="chatbot-container"></div>

<!-- Initialize -->
<script>
  ChatbotUI.init('chatbot-container', {
    config: {
      apiUrl: 'https://your-api.com/api/chat',
    },
    theme: {
      primaryColor: '#3b82f6',
      userMessageColor: '#3b82f6',
      assistantMessageColor: '#f1f5f9',
    },
  });
</script>

Building for CDN:

# Build browser bundle
npm run build:browser
# or
pnpm build:browser

# Output files will be in dist/browser/:
# - chatbot-ui.min.js (production)
# - chatbot-ui.js (development)
# - chatbot-ui.css (styles)
# - cdn-example.html (example file)

Iframe Embedding

After building, you can embed the chatbot in an iframe:

<iframe 
  src="https://cdn.example.com/chatbot.html?apiUrl=https://your-api.com/api/chat"
  width="400" 
  height="600"
  frameborder="0">
</iframe>

CSS Setup

Import the CSS file in your project:

@import 'acecoderz-chat-ui/styles';

Or in your JavaScript/TypeScript:

import 'acecoderz-chat-ui/styles';

Usage

React

import { ChatUI } from 'acecoderz-chat-ui/react';
import 'acecoderz-chat-ui/styles';

function App() {
  return (
    <ChatUI
      config={{
        apiUrl: 'http://localhost:3000/api',
      }}
      theme={{
        primaryColor: '#3b82f6',
        userMessageColor: '#3b82f6',
      }}
    />
  );
}

Or use the hook directly:

import { useChat } from 'acecoderz-chat-ui/react';

function CustomChat() {
  const { messages, input, sendMessage, setInput } = useChat({
    apiUrl: 'http://localhost:3000/api',
  });

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <input value={input} onChange={e => setInput(e.target.value)} />
      <button onClick={() => sendMessage(input)}>Send</button>
    </div>
  );
}

Solid

import { createChat } from 'acecoderz-chat-ui/solid';
import 'acecoderz-chat-ui/styles';

function App() {
  const chat = createChat({
    apiUrl: 'http://localhost:3000/api',
  });

  return (
    <div>
      <For each={chat.messages()}>
        {(msg) => <div>{msg.content}</div>}
      </For>
      <input 
        value={chat.input()} 
        onInput={e => chat.setInput(e.target.value)} 
      />
      <button onClick={() => chat.sendMessage(chat.input())}>
        Send
      </button>
    </div>
  );
}

Vanilla JS

import { createChatUI } from 'acecoderz-chat-ui/vanilla';
import 'acecoderz-chat-ui/styles';

const container = document.getElementById('chat-container');

const chatUI = createChatUI({
  config: {
    apiUrl: 'http://localhost:3000/api',
    enablePersistence: true, // Optional: Save messages to localStorage
    storageKey: 'my-chat-app', // Optional: Custom storage key
  },
  theme: {
    primaryColor: '#3b82f6',
  },
  container,
  // Optional: Enable message actions (copy, delete, edit)
  enableMessageActions: true,
  showCopyButton: true,
  showDeleteButton: true,
  showEditButton: true,
});

// Later, to destroy:
// chatUI.destroy();

Note: The vanilla adapter now handles form submission automatically - no workarounds needed! See INTEGRATION_GUIDE.md for complete integration examples.

Core Only (Advanced)

import { ChatEngine } from 'acecoderz-chat-ui/core';

const engine = new ChatEngine({
  apiUrl: 'http://localhost:3000/api',
});

engine.on('messagesChange', (messages) => {
  console.log('Messages updated:', messages);
});

engine.sendMessage('Hello!');

Theming

CSS Variables

The package uses CSS variables for theming. You can override them:

.chat-container {
  --chat-primary-color: #your-color;
  --chat-user-message-color: #your-color;
  --chat-assistant-message-color: #your-color;
  --chat-border-radius: 0.5rem;
  --chat-font-family: 'Your Font', sans-serif;
  /* ... and more */
}

Theme Props (React)

<ChatUI
  config={config}
  theme={{
    primaryColor: '#3b82f6',
    userMessageColor: '#3b82f6',
    assistantMessageColor: '#f1f5f9',
    borderRadius: '0.5rem',
    fontFamily: 'system-ui, sans-serif',
  }}
/>

Configuration

interface ChatConfig {
  apiUrl?: string;              // Backend API URL
  apiKey?: string;              // API key for authentication
  headers?: Record<string, string>; // Custom headers
  onMessage?: (message: Message) => void; // Message callback
  onError?: (error: Error) => void; // Error callback
  enableWebSocket?: boolean;    // Enable WebSocket
  websocketUrl?: string;        // WebSocket URL
  enablePersistence?: boolean;  // Enable localStorage persistence (default: false)
  storageKey?: string;          // Storage key prefix (default: 'chat-ui')
}

New Features

Message Persistence

Automatically save and restore conversations across page reloads:

const chatUI = createChatUI({
  config: {
    apiUrl: '/api/chat',
    enablePersistence: true, // Enable localStorage
    storageKey: 'my-app', // Optional: custom key
  },
  container: document.getElementById('chat'),
});

Message Actions

Enable copy, delete, and edit buttons on messages:

const chatUI = createChatUI({
  config: { apiUrl: '/api/chat' },
  container: document.getElementById('chat'),
  enableMessageActions: true,
  showCopyButton: true,
  showDeleteButton: true,
  showEditButton: true,
  onMessageCopy: (message) => console.log('Copied:', message.content),
  onMessageDelete: (message) => console.log('Deleted:', message.id),
  onMessageEdit: (message, newContent) => console.log('Edited:', newContent),
});

Initial Greeting

Display a welcome message when the chat first opens:

Vanilla JS:

const chatUI = createChatUI({
  config: { apiUrl: '/api/chat' },
  container: document.getElementById('chat'),
  initialGreeting: "Hello! 👋 I'm your assistant. How can I help you today?",
});

React:

<ChatUI
  config={config}
  initialGreeting="Hello! 👋 I'm your assistant. How can I help you today?"
/>

The greeting will:

• Appear automatically when the chat opens
• Only show once per conversation
• Reappear after clearing the chat
• Not trigger an API call (it's a local message)

Improved Loading States

• Animated loading indicators
• Better accessibility with ARIA live regions
• Smooth transitions

See NEW_FEATURES.md for complete feature documentation.

Integration Guide

For complete integration instructions, examples, and troubleshooting, see the Integration Guide.

The integration guide includes:

• Complete vanilla JS examples with modal
• React integration examples
• Backend configuration
• Feature documentation
• Troubleshooting guide

Laravel Integration

For Laravel-specific integration with modal interface, event handling, and CORS configuration, see LARAVEL_INTEGRATION.md.

The Laravel integration guide includes:

• Complete setup instructions
• Blade template examples
• Event handling for Laravel forms
• CORS configuration
• Troubleshooting common issues

Customization

Custom Message Renderer (React)

<ChatUI
  config={config}
  customMessageRenderer={(message) => (
    <div className="my-custom-message">
      {message.content}
    </div>
  )}
/>

Custom Input Renderer (React)

<ChatUI
  config={config}
  customInputRenderer={({ value, onChange, onSend, disabled }) => (
    <div>
      <textarea value={value} onChange={e => onChange(e.target.value)} />
      <button onClick={onSend} disabled={disabled}>Send</button>
    </div>
  )}
/>

Backend API

The package expects a backend API with the following endpoint:

POST /api/chat

Request:

{
  "message": "Hello!",
  "conversationId": "optional-conversation-id"
}

Response:

{
  "id": "message-id",
  "message": "Response message",
  "content": "Response message",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "metadata": {}
}

License

MIT