Package Reference

Quick Start Guide

The five-minute overview

If you already finished Installation and Project Setup, this page gets you to a working chat page quickly. The checklist below is the shortest path from zero to ChatMain.

Install the package plus its peers: react, react-dom, zustand, and Tailwind CSS v4.
Import CSS: @import "@realtimexsco/live-chat/styles.css" and add Tailwind @source entries for the package dist files.
Create chat.config.ts with clientId, accessToken, loggedUserDetails, apiUrl, and socketUrl.
Render <ChatMain {...chatConfig} /> inside a height-bounded container — the package provides a built-in viewport wrapper.
Optionally pass components, classNames, or features to customize. Omit any slot and the package default is used automatically.

Minimum working chat

This is the smallest page that should render a functional chat once CSS and credentials are configured. On Next.js, keep "use client" at the top of any file that imports the package.

tsx

"use client"; // Next.js only — required on any file that imports chat
import ChatMain from "@realtimexsco/live-chat";
import { chatConfig } from "@/configs/chat.config";

export default function ChatPage() {
  return (
    <div className="h-dvh min-h-0 overflow-hidden">
      <ChatMain
        clientId={chatConfig.clientId}
        accessToken={chatConfig.accessToken}
        loggedUserDetails={chatConfig.loggedUserDetails}
        apiUrl={chatConfig.apiUrl}
        socketUrl={chatConfig.socketUrl}
        themeColor={chatConfig.themeColor}
      />
    </div>
  );
}

Viewport height patterns

Choose a height strategy that matches your shell. Without a bounded height, the browser scrolls the whole page instead of the message list.

tsx

// Full page
<ChatMain {...chatConfig} viewportHeight="screen" />

// Admin shell with a 4rem header (Elstar, Metronic, etc.)
<ChatMain {...chatConfig} viewportHeight="calc(100dvh - 4rem)" />

// Inside your own bounded flex column
<div className="flex min-h-0 flex-1 overflow-hidden">
  <ChatMain {...chatConfig} viewportHeight="full" />
</div>

Complete example with theme, locale, layout, and calls

The example below shows a production-shaped page: color mode state, locale/timezone, layout defaults, a custom Avatar slot, classNames, and phone/video feature callbacks. Start from the minimum example above, then layer these options as needed.

tsx

"use client";
import { useState } from "react";
import ChatMain, {
  type ChatColorMode,
  type ChatComponents,
  type ChatClassNames,
  type ChatFeatures,
  type AvatarSlotProps,
  defaultChatLayoutConfig,
} from "@realtimexsco/live-chat";
import { chatConfig } from "@/configs/chat.config";

const MyAvatar = ({ src, name, size }: AvatarSlotProps) => (
  <img
    src={src || undefined}
    alt={name}
    className={`rounded-full object-cover avatar--${size}`}
    style={{ width: 36, height: 36 }}
  />
);

const components: ChatComponents = { Avatar: MyAvatar };

const classNames: ChatClassNames = {
  sidebar: "bg-slate-950",
  channelHeader: "border-b-2 border-indigo-500",
  messageBubbleSender: "rounded-3xl shadow-md",
};

const features: ChatFeatures = {
  showPhoneCall: true,
  showVideoCall: true,
  onPhoneCall: ({ activeChannel, conversationId }) => {
    console.log("Voice call", activeChannel.name, conversationId);
  },
};

export default function ChatPage() {
  const [colorMode, setColorMode] = useState<ChatColorMode>("light");

  return (
    <div className="h-dvh min-h-0 overflow-hidden">
      <ChatMain
        {...chatConfig}
        colorMode={colorMode}
        onColorModeChange={setColorMode}
        showColorModeToggle={false}
        locale="en-US"
        timeZone="Asia/Kolkata"
        hour12={false}
        layout={{ ...defaultChatLayoutConfig }}
        components={components}
        classNames={classNames}
        features={features}
      />
    </div>
  );
}

"use client"; // Next.js only — required on any file that imports chat import ChatMain from "@realtimexsco/live-chat"; import { chatConfig } from "@/configs/chat.config"; export default function ChatPage() { return ( <div className="h-dvh min-h-0 overflow-hidden"> <ChatMain clientId={chatConfig.clientId} accessToken={chatConfig.accessToken} loggedUserDetails={chatConfig.loggedUserDetails} apiUrl={chatConfig.apiUrl} socketUrl={chatConfig.socketUrl} themeColor={chatConfig.themeColor} /> </div> ); }

// Full page <ChatMain {...chatConfig} viewportHeight="screen" /> // Admin shell with a 4rem header (Elstar, Metronic, etc.) <ChatMain {...chatConfig} viewportHeight="calc(100dvh - 4rem)" /> // Inside your own bounded flex column <div className="flex min-h-0 flex-1 overflow-hidden"> <ChatMain {...chatConfig} viewportHeight="full" /> </div>

"use client"; import { useState } from "react"; import ChatMain, { type ChatColorMode, type ChatComponents, type ChatClassNames, type ChatFeatures, type AvatarSlotProps, defaultChatLayoutConfig, } from "@realtimexsco/live-chat"; import { chatConfig } from "@/configs/chat.config"; const MyAvatar = ({ src, name, size }: AvatarSlotProps) => ( <img src={src || undefined} alt={name} className={`rounded-full object-cover avatar--${size}`} style={{ width: 36, height: 36 }} /> ); const components: ChatComponents = { Avatar: MyAvatar }; const classNames: ChatClassNames = { sidebar: "bg-slate-950", channelHeader: "border-b-2 border-indigo-500", messageBubbleSender: "rounded-3xl shadow-md", }; const features: ChatFeatures = { showPhoneCall: true, showVideoCall: true, onPhoneCall: ({ activeChannel, conversationId }) => { console.log("Voice call", activeChannel.name, conversationId); }, }; export default function ChatPage() { const [colorMode, setColorMode] = useState<ChatColorMode>("light"); return ( <div className="h-dvh min-h-0 overflow-hidden"> <ChatMain {...chatConfig} colorMode={colorMode} onColorModeChange={setColorMode} showColorModeToggle={false} locale="en-US" timeZone="Asia/Kolkata" hour12={false} layout={{ ...defaultChatLayoutConfig }} components={components} classNames={classNames} features={features} /> </div> ); }