mern-chatkit-ui

A plug-and-play real-time chat UI component for React (Vite) that works seamlessly with the mern-chatkit backend.

✨ Features

• 📱 Responsive Design - WhatsApp/Messenger-like UI
• 🌙 Dark/Light Mode - Built-in theme support
• 💬 Real-time Messaging - Socket.io integration
• 📎 File Attachments - Images and files support
• 😊 Emoji Picker - Quick emoji insertion
• ⌨️ Typing Indicators - See when users are typing
• 🟢 Online Status - Real-time user presence
• ✓✓ Read Receipts - Seen/unseen message status
• 🔍 Search - Filter conversations

📦 Installation

npm install mern-chatkit-ui socket.io-client

Also ensure you have Tailwind CSS configured in your project.

🚀 Quick Start

import React from 'react';
import { ChatKit } from 'mern-chatkit-ui';

function App() {
  const user = {
    id: 'user123',
    name: 'John Doe',
    avatar: 'https://example.com/avatar.jpg'
  };
  
  const token = 'your-jwt-token';

  return (
    <div className="h-screen">
      <ChatKit
        user={user}
        token={token}
        apiBaseUrl="http://localhost:5000/api"
        socketUrl="http://localhost:5000"
        theme="light"
      />
    </div>
  );
}

export default App;

📋 Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | user | object | ✅ | Logged-in user info { id, name, avatar } | | token | string | ✅ | JWT token for API authentication | | apiBaseUrl | string | ✅ | Backend REST API URL | | socketUrl | string | ✅ | Backend Socket.io URL | | theme | string | ❌ | "light" or "dark" (default: "light") |

🪝 Hooks

The package exports reusable hooks for custom implementations:

import {
  useChat,
  useConversations,
  useMessages,
  useSendMessage,
  useTyping,
  useOnlineStatus
} from 'mern-chatkit-ui';

// useChat - Access all chat context
const { user, conversations, activeConversation, messages } = useChat();

// useConversations - Manage conversations list
const { conversations, loading, query, setQuery } = useConversations();

// useMessages - Get messages for a conversation
const { messages, loading } = useMessages(conversationId);

// useSendMessage - Send messages
const { send } = useSendMessage();
await send(conversationId, { text: 'Hello!', files: [] });

// useTyping - Typing indicators
const { start, stop } = useTyping(conversationId);

// useOnlineStatus - Check user online status
const isOnline = useOnlineStatus(userId);

// useUserSearch - Search for users to chat with
const { users, loading, query, setQuery } = useUserSearch();

// useCreateConversation - Create new conversations
const { createConversation, loading } = useCreateConversation();
await createConversation(['userId1'], false); // Direct message
await createConversation(['userId1', 'userId2'], true, 'Group Name'); // Group chat

🆕 Starting New Conversations

The package includes a built-in New Chat button (➕) in the sidebar that allows users to:

1. Search for users - Find other users to chat with
2. Direct Message - Start a one-on-one conversation
3. Group Chat - Create a group with multiple users

You can also use the NewChatModal component directly:

import { NewChatModal } from 'mern-chatkit-ui';

function MyComponent() {
  const [showModal, setShowModal] = useState(false);
  
  return (
    <>
      <button onClick={() => setShowModal(true)}>New Chat</button>
      <NewChatModal isOpen={showModal} onClose={() => setShowModal(false)} />
    </>
  );
}

🔌 Required Backend Setup

This UI package is designed to work with mern-chatkit backend. The backend must expose:

REST API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /users/search | Search users (new!) | | POST | /conversations | Create new conversation (new!) | | GET | /conversations | List all conversations | | GET | /conversations/:id/messages | Get messages for conversation | | POST | /conversations/:id/messages | Send a message | | POST | /conversations/:id/seen | Mark messages as seen | | POST | /conversations/:id/files | Upload files |

Socket.io Events

| Event | Direction | Description | |-------|-----------|-------------| | message:receive | Server → Client | New message received | | message:send | Client → Server | Send a message | | typing:start | Bidirectional | User started typing | | typing:stop | Bidirectional | User stopped typing | | user:online | Server → Client | User came online | | user:offline | Server → Client | User went offline |

📁 Package Structure

src/
├── components/
│   ├── ChatKit.jsx      # Main component
│   ├── Sidebar.jsx      # Conversations list
│   ├── ChatWindow.jsx   # Message display area
│   ├── Message.jsx      # Individual message
│   ├── MessageInput.jsx # Input with emoji/file
│   └── Header.jsx       # Conversation header
├── hooks/
│   ├── useChat.js         # Main chat hook
│   ├── useConversations.js
│   ├── useMessages.js
│   ├── useSendMessage.js
│   ├── useTyping.js
│   └── useOnlineStatus.js
├── context/
│   └── ChatProvider.jsx # React context provider
├── utils/
│   ├── api.js           # API client
│   └── socket.js        # Socket.io client
└── index.js             # Package exports

🎨 Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                         ChatKit                              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
│  │    Sidebar      │    │         ChatWindow              │ │
│  │                 │    │  ┌───────────────────────────┐  │ │
│  │  ┌───────────┐  │    │  │        Header             │  │ │
│  │  │  Search   │  │    │  └───────────────────────────┘  │ │
│  │  └───────────┘  │    │  ┌───────────────────────────┐  │ │
│  │                 │    │  │       Messages            │  │ │
│  │  ┌───────────┐  │    │  │  ┌─────────────────────┐  │  │ │
│  │  │  Conv 1   │  │    │  │  │     Message        │  │  │ │
│  │  ├───────────┤  │    │  │  └─────────────────────┘  │  │ │
│  │  │  Conv 2   │  │    │  │  ┌─────────────────────┐  │  │ │
│  │  ├───────────┤  │    │  │  │     Message        │  │  │ │
│  │  │  Conv 3   │  │    │  │  └─────────────────────┘  │  │ │
│  │  └───────────┘  │    │  └───────────────────────────┘  │ │
│  │                 │    │  ┌───────────────────────────┐  │ │
│  └─────────────────┘    │  │     MessageInput         │  │ │
│                         │  │  [📎] [😊] [___________] [➤]│  │ │
│                         │  └───────────────────────────┘  │ │
│                         └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
           │                           │
           ▼                           ▼
    ┌──────────────┐           ┌──────────────┐
    │   REST API   │           │  Socket.io   │
    │  (axios)     │           │  (real-time) │
    └──────────────┘           └──────────────┘
           │                           │
           └───────────┬───────────────┘
                       ▼
              ┌──────────────────┐
              │  mern-chatkit    │
              │    Backend       │
              └──────────────────┘

🎯 Goal

Add a fully functional real-time chat UI to any React app with just:

<ChatKit user={user} token={jwt} apiBaseUrl="..." socketUrl="..." />

📄 License

MIT