react-smart-chat-ui

A production-ready, highly customizable React Chat UI library with WhatsApp, ChatGPT, Gemini, and Default themes.

✨ Features

• 🎨 4 built-in themes — Default, WhatsApp, ChatGPT, Gemini
• 🧩 Headless core — use individual components with your own CSS
• ⚙️ Fully customizable — colors, fonts, bubble shapes, spacing, avatars, timestamps
• 📦 Zero runtime dependencies — only React as a peer dep
• 🔷 TypeScript first — full type coverage
• ♿ Accessible — ARIA roles, keyboard navigation
• 🌗 CSS custom properties — easy runtime theme switching
• 🌳 Tree-shakeable — import only what you use

📦 Installation

npm install react-smart-chat-ui

🚀 Quick start

import { ChatUI } from 'react-smart-chat-ui';
import 'react-smart-chat-ui/dist/style.css';

const messages = [
  {
    id: '1',
    sender: 'bot',
    senderName: 'Assistant',
    text: 'Hello! How can I help you today?',
    timestamp: new Date(),
  },
];

export default function App() {
  const [msgs, setMsgs] = useState(messages);

  function handleSend(text: string) {
    setMsgs(prev => [...prev, {
      id: Date.now().toString(),
      sender: 'user',
      text,
      timestamp: new Date(),
      status: 'sent',
    }]);
  }

  return (
    <div style={{ height: 600 }}>
      <ChatUI
        messages={msgs}
        onSend={handleSend}
        currentUserId="user"
      />
    </div>
  );
}

🎨 Themes

WhatsApp

<ChatUI
  theme="whatsapp"
  messages={messages}
  onSend={handleSend}
  currentUserId="user"
  options={{
    headerTitle:    'Alice',
    headerSubtitle: 'Online',
    showAvatars:    true,
    showTimestamps: true,
    bubbleStyle:    'rounded',
  }}
/>

ChatGPT

<ChatUI
  theme="chatgpt"
  messages={messages}
  onSend={handleSend}
  currentUserId="user"
  options={{
    headerTitle:    'ChatGPT',
    headerSubtitle: 'GPT-4o',
    showAvatars:    false,
    showTimestamps: false,
    bubbleStyle:    'sharp',
    spacing:        'comfortable',
  }}
/>

Gemini

<ChatUI
  theme="gemini"
  messages={messages}
  onSend={handleSend}
  currentUserId="user"
  options={{
    headerTitle:    'Gemini',
    headerSubtitle: '1.5 Pro',
    showAvatars:    true,
    showTimestamps: true,
    bubbleStyle:    'pill',
  }}
/>

⚙️ Props

<ChatUI />

| Prop | Type | Default | Description | |---|---|---|---| | messages | Message[] | required | Array of message objects | | onSend | (text: string) => void | required | Called when user submits | | theme | 'default' \| 'whatsapp' \| 'chatgpt' \| 'gemini' | 'default' | Visual theme | | currentUserId | string | 'user' | Messages from this sender appear on the right | | options | ChatOptions | {} | Fine-grained options (see below) | | isTyping | boolean | false | Shows animated typing indicator | | className | string | — | Extra CSS class on root | | style | CSSProperties | — | Extra inline style on root | | headerActions | ReactNode | — | Slot for header right-side actions | | onBack | () => void | — | Shows back arrow and calls this on click |

ChatOptions

| Option | Type | Default | Description | |---|---|---|---| | showAvatars | boolean | true | Show avatar circles | | showTimestamps | boolean | true | Show timestamps below bubbles | | showHeader | boolean | true | Show the header bar | | headerTitle | string | 'Chat' | Header title | | headerSubtitle | string | '' | Header subtitle / status | | headerAvatar | string | '' | Header avatar image URL | | bubbleStyle | 'rounded' \| 'sharp' \| 'pill' | 'rounded' | Bubble corner style | | fontSize | 'sm' \| 'md' \| 'lg' | 'md' | Font size preset | | spacing | 'compact' \| 'comfortable' | 'comfortable' | Message density | | placeholder | string | 'Type a message…' | Input placeholder | | currentUserId | string | 'user' | Own-message identifier |

Message

interface Message {
  id:          string;
  text:        string;
  sender:      string;         // compared against currentUserId
  timestamp:   Date;
  avatar?:     string;         // image URL
  senderName?: string;         // display name
  status?:     'sending' | 'sent' | 'delivered' | 'read' | 'failed';
}

🧩 Headless usage

You can compose the UI from individual core components and provide your own CSS:

import {
  ChatProvider,
  ChatContainer,
  ChatHeader,
  MessageList,
  InputBar,
} from 'react-smart-chat-ui';
import 'react-smart-chat-ui/dist/style.css';
import './my-theme.css'; // override CSS custom properties

export function MyChatUI({ messages, onSend }) {
  return (
    <ChatProvider theme="default" currentUserId="me">
      <ChatContainer>
        <ChatHeader title="Support" subtitle="Online" />
        <MessageList messages={messages} />
        <InputBar onSend={onSend} />
      </ChatContainer>
    </ChatProvider>
  );
}

Custom theme via CSS variables

Override any variable inside your own CSS to fully restyle the chat:

.rscui[data-theme="default"] {
  --rscui-b-own-bg:   #7c3aed;   /* purple user bubbles */
  --rscui-b-own-fg:   #ffffff;
  --rscui-send-bg:    #7c3aed;
  --rscui-header-bg:  #1e1b4b;
  --rscui-header-fg:  #e0e7ff;
}

🛠 Development

# Clone
git clone https://github.com/Hazhtech-Solutions/chatui.git
cd react-smart-chat-ui

# Install deps
npm install

# Start demo dev server (http://localhost:3000)
npm run dev

# Type-check
npm run type-check

# Build library → dist/
npm run build

# Build static demo → demo/dist/
npm run build:demo

# Preview the built demo
npm run preview

🌐 Deploy demo to Hostinger

1. Build the static demo:

   npm run build:demo

2. The output is in demo/dist/ — a fully static site (HTML + JS + CSS).
3. In Hostinger File Manager (or via FTP/SFTP), upload the contents of demo/dist/ to public_html/.
4. Done — no server-side rendering needed.

Tip: If you deploy to a sub-path (e.g. yourdomain.com/chat-ui/), set base: '/chat-ui/' in demo/vite.config.ts before building.

📤 Publish to npm

# Ensure you're logged in
npm login

# Bump version, build, and publish
npm version patch   # or minor / major
npm publish

❤️ Support the project

If this library saves you time, consider sponsoring development:

• GitHub Sponsors
• Buy Me a Coffee
• Open Collective

Every contribution helps keep this project maintained and growing. Thank you! 🙏

🗺 Roadmap

• [ ] Slack theme
• [ ] Telegram theme
• [ ] iMessage theme
• [ ] File/image attachments
• [ ] Emoji picker integration
• [ ] Reply-to / quote messages
• [ ] Unread message badge
• [ ] Virtual scrolling (for very long histories)
• [ ] Plugin API for custom bubble types
• [ ] React Native adapter (Pro)
• [ ] Storybook documentation

📄 License

MIT © Hazhtech Solutions