Introduction

@realtimexsco/live-chat is a complete, drop-in real-time chat UI for React and Next.js. It ships direct messages, group conversations, reactions, replies, forwarding, pinning, starring, attachments, in-chat search, light/dark themes, and locale-aware formatting — wired to a REST API and Socket.IO out of the box.

The package bundles its own HTTP client (Axios), realtime client (Socket.IO), state management (Zustand), UI primitives (Radix UI), icons (Lucide), and an emoji picker. Consumers only need a small set of peer dependencies — React, Zustand, and Tailwind CSS v4 — everything else ships inside the package.

Customization is opt-in: every visual slot (avatar, message bubble, header, drawers, and more) renders a sensible default. Supply a replacement only for the parts you want to change.

Suggested path: Prerequisites → Installation → Project Setup → Quick Start.

• Direct messages (1-to-1) and group chats
• Real-time delivery over Socket.IO with optimistic (instant) sending
• Reactions, replies, and message forwarding
• Edit and delete messages (for me / for everyone)
• Pin and star important messages
• Attachments — images and files
• In-chat message search
• Typing indicators and read receipts (sent / delivered / read)
• New chat / user picker modal
• Group members, admins, and permission management
• Light and dark mode with a runtime brand color
• Locale and timezone-aware date/time formatting
• Phone and video call integration hooks (you wire the WebRTC/SDK layer)
• Full UI customization — replace the entire shell, individual components, or just CSS classes

At the top, ChatMain composes a theme provider, a locale provider, the Chat data provider (authentication, REST client, socket connection, and the Zustand store), a customization provider, and an alerts provider. Inside, ChatLayout resolves either your custom layout or the built-in DefaultChatLayout, which renders a sidebar (profile + conversation list) and a main panel (header, message list, and composer). Every replaceable UI region is resolved through a single resolveComponent(slot, PackageDefault) call: if you supplied a component for that slot it is used, otherwise the package default renders.

Runtime data flow, at a glance:

• ChatMain performs client-user login, stores the JWT, and opens the socket connection.
• The user selects a conversation, which triggers a message fetch and a socket room join.
• Sending a message is optimistic: it appears immediately in the UI and reconciles once the server acknowledges it.
• Incoming socket events update the Zustand store, and subscribed components re-render automatically.

ChatMain
|-- ChatThemeProvider        (themeColor, light/dark)
|-- ChatLocaleProvider       (locale, timezone, hour12)
|-- Chat
|     |-- Auth + REST API + Socket.IO + Zustand store
|     |-- ChatCustomizationProvider  (components, classNames, features)
|           |-- ChatLayout  (resolveComponent -> Default or custom)
|                 |-- Sidebar: LoggedUserDetails + ChannelList
|                 |-- Main: ChannelHeader + MessageList + MessageInput
|                       |-- ChannelHeaderView
|                             |-- drawers (Members, Details, ...)
|                             |-- modals (Clear, Delete, Block)
|-- ChatAlertsProvider       (error / info banner)