@cundi/react-chat-widget

A flexible React chat widget with support for both callback and webhook modes.

Features

• 🎨 Ant Design inspired styling with light/dark themes
• 📝 Markdown rendering with GFM support
• 📊 Mermaid diagrams support
• 📋 Code blocks with copy button
• 📎 File upload/download support
• 🖼️ Image paste (Ctrl+V)
• 👤 Customizable avatars and names
• 🔌 Two modes: Callback (custom handling) or Webhook (n8n, etc.)

Installation

npm install @cundi/react-chat-widget
# or
pnpm add @cundi/react-chat-widget

Usage

Callback Mode (Custom Message Handling)

Use this mode when you want to handle messages with your own logic (e.g., calling AI APIs).

import { ChatWidget } from '@cundi/react-chat-widget';

function App() {
  const handleMessage = async (message: string) => {
    // Call your AI API or process the message
    const response = await myAI.chat(message);
    return { output: response };
  };

  return (
    <ChatWidget
      onSendMessage={handleMessage}
      user={{ name: 'User', avatar: '👤' }}
      assistant={{ name: 'AI', avatar: '🤖' }}
    />
  );
}

Webhook Mode (n8n, External Services)

Use this mode to connect to external webhook endpoints like n8n Chat Triggers.

import { ChatWidget } from '@cundi/react-chat-widget';

function App() {
  return (
    <ChatWidget
      webhookUrl="https://your-n8n.com/webhook/chat-trigger-id"
      sessionId="unique-session-id"
      user={{ name: 'User', avatar: '👤' }}
      assistant={{ name: 'n8n Bot', avatar: '🤖' }}
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onSendMessage | (message: string, files?: File[]) => Promise<ChatResponse \| string> | - | Callback for handling messages | | webhookUrl | string | - | Webhook URL for external services | | sessionId | string | - | Session ID for conversation memory | | theme | 'light' \| 'dark' | 'light' | Theme mode | | title | string | 'Chat' | Chat header title | | placeholder | string | 'Type a message...' | Input placeholder | | allowFileUpload | boolean | false | Enable file upload | | maxFileSize | number | 10485760 | Max file size (bytes) | | showHeader | boolean | true | Show chat header | | user | AvatarConfig | - | User avatar and name | | assistant | AvatarConfig | - | Assistant avatar and name | | onMessage | (message: Message) => void | - | Callback when message received | | onError | (error: Error) => void | - | Callback on error |

Response Format

When using onSendMessage, return a ChatResponse object:

interface ChatResponse {
  output: string;        // Required: text content
  image?: string;        // Optional: single image URL
  images?: string[];     // Optional: multiple image URLs
  files?: Array<{        // Optional: file attachments
    name: string;
    url: string;
    type: string;
    size?: number;
  }>;
}

License

MIT