Package Reference

Configuration Options

Prop reference

All configuration is passed as props to ChatMain (or, in composable mode, to Chat and uiConfig). The table below lists every available prop, its type, default, and purpose. Worked examples for the most common groups follow after the table.

Prop	Type	Default	Description
clientId	string	—	Required. Tenant / client id
accessToken	string	—	Required. JWT access token
loggedUserDetails	object	—	Required. { _id, name, email } — _id must match the JWT
apiUrl	string	—	Required. REST API base URL, must end with /api/v1
socketUrl	string	derived	Optional socket host (no /api/v1). Defaults to apiUrl without /api/v1
queryParams	Record<string, string \| number \| boolean>	—	Shared query params applied to APIs selected by queryParamApis
queryParamApis	ChatApiKey[]	['get']	Which API groups receive queryParams ("get", "all", or specific keys)
queryParamsByApi	ChatQueryParamsByApi	—	Different query params per API key (including presignedUrls)
viewportHeight	"full" \| "screen" \| string	"full"	Chat root height — use "screen" or a calc() under a fixed app header so only the message list scrolls
viewportClassName	string	—	Extra classes on the built-in viewport wrapper
themeColor	string	—	Brand accent hex; writes --chat-theme* CSS variables at runtime
colorMode	"light" \| "dark"	—	Controlled light/dark mode
defaultColorMode	"light" \| "dark"	"light"	Initial mode when uncontrolled
onColorModeChange	(mode) => void	—	Called when the theme changes
showColorModeToggle	boolean	true	Show the built-in light/dark toggle
locale	string	browser	BCP 47 locale, e.g. "en-US"
timeZone	string	browser	IANA timezone, e.g. "Asia/Kolkata"
hour12	boolean	locale	true = 12-hour clock
showDateTimeSettings	boolean	true	Show the in-panel date/time button
layout	ChatLayoutConfig	all true	Toggle visibility of UI sections
components	ChatComponents	—	Replace UI slots — see Customization and Components
classNames	ChatClassNames	—	Per-region CSS class overrides (merged with defaults)
features	ChatFeatures	—	Phone/video call flags and callbacks
uiConfig	UIConfig	—	Advanced bag merged with components / classNames / features when using the composable Chat entry
error / info	string \| null	—	Message shown in the alert bar
onErrorDismiss / onInfoDismiss	() => void	—	Dismiss the alert bar

Credentials and endpoints

These props are required for a working session. Keep them in chat.config.ts and ensure loggedUserDetails._id matches the JWT. See Prerequisites for field notes.

tsx

<ChatMain
  clientId={chatConfig.clientId}
  accessToken={chatConfig.accessToken}
  loggedUserDetails={chatConfig.loggedUserDetails}
  apiUrl={chatConfig.apiUrl}
  socketUrl={chatConfig.socketUrl}
/>

Viewport, theme, and locale

Set height so the chat fills the available viewport without scrolling the whole page. Theme and locale props control accent color and timestamp formatting across every slot.

tsx

<ChatMain
  {...chatConfig}
  viewportHeight="calc(100dvh - 4rem)"
  themeColor="#6366f1"
  defaultColorMode="light"
  locale="en-US"
  timeZone="Asia/Kolkata"
  hour12={true}
/>

Query parameters

Attach shared or per-endpoint query strings to package REST calls. Defaults apply queryParams to GET APIs only. Full patterns live in API Integration.

tsx

<ChatMain
  {...chatConfig}
  queryParams={{ tenant: "acme" }}
  queryParamApis={["get"]}
  queryParamsByApi={{
    conversations: { includeArchived: false },
    presignedUrls: { folder: "chat-uploads" },
  }}
/>

Customization props

Use components, classNames, and features together. Deep guides: Customization and Components.

tsx

<ChatMain
  {...chatConfig}
  components={{ Avatar: MyAvatar }}
  classNames={{ messageBubbleSender: "rounded-2xl" }}
  features={{
    showPhoneCall: true,
    onPhoneCall: ({ conversationId }) => startCall(conversationId),
  }}
/>

Layout sections (layout prop)

Toggle parts of the default UI on or off without writing any new components. Spread defaultChatLayoutConfig and flip only the sections you need.

tsx

import { defaultChatLayoutConfig } from "@realtimexsco/live-chat";

export const chatLayoutConfig = {
  ...defaultChatLayoutConfig,
  // sidebar: true,           // left panel wrapper
  // loggedUserDetails: true, // profile + new chat button
  // channelList: true,       // conversation list
  // header: true,            // channel header bar
  // messageList: true,       // message bubbles
  // input: true,             // composer
  // forwardModal: true,      // forward dialog
};

tsx

layout={{ input: false }}          // read-only, no composer
layout={{ sidebar: false }}         // hide sidebar, messages only
layout={{ forwardModal: false }}    // disable the forward modal
layout={{ loggedUserDetails: false, channelList: true }}

Prop

Type

Default

Description

clientId

string

—

Required. Tenant / client id

accessToken

string

—

Required. JWT access token

loggedUserDetails

object

—

Required. { _id, name, email } — _id must match the JWT

apiUrl

string

—

Required. REST API base URL, must end with /api/v1

socketUrl

string

derived

Optional socket host (no /api/v1). Defaults to apiUrl without /api/v1

queryParams

Record<string, string | number | boolean>

—

Shared query params applied to APIs selected by queryParamApis

queryParamApis

ChatApiKey[]

['get']

Which API groups receive queryParams ("get", "all", or specific keys)

queryParamsByApi

ChatQueryParamsByApi

—

Different query params per API key (including presignedUrls)

viewportHeight

"full" | "screen" | string

"full"

Chat root height — use "screen" or a calc() under a fixed app header so only the message list scrolls

viewportClassName

string

—

Extra classes on the built-in viewport wrapper

themeColor

string

—

Brand accent hex; writes --chat-theme* CSS variables at runtime

colorMode

"light" | "dark"

—

Controlled light/dark mode

defaultColorMode

"light" | "dark"

"light"

Initial mode when uncontrolled

onColorModeChange

(mode) => void

—

Called when the theme changes

showColorModeToggle

boolean

true

Show the built-in light/dark toggle

locale

string

browser

BCP 47 locale, e.g. "en-US"

timeZone

string

browser

IANA timezone, e.g. "Asia/Kolkata"

hour12

boolean

locale

true = 12-hour clock

showDateTimeSettings

boolean

true

Show the in-panel date/time button

layout

ChatLayoutConfig

all true

Toggle visibility of UI sections

components

ChatComponents

—

Replace UI slots — see Customization and Components

classNames

ChatClassNames

—

Per-region CSS class overrides (merged with defaults)

features

ChatFeatures

—

Phone/video call flags and callbacks

uiConfig

UIConfig

—

Advanced bag merged with components / classNames / features when using the composable Chat entry

error / info

string | null

—

Message shown in the alert bar

onErrorDismiss / onInfoDismiss

() => void

—

Dismiss the alert bar

<ChatMain {...chatConfig} queryParams={{ tenant: "acme" }} queryParamApis={["get"]} queryParamsByApi={{ conversations: { includeArchived: false }, presignedUrls: { folder: "chat-uploads" }, }} />

<ChatMain {...chatConfig} components={{ Avatar: MyAvatar }} classNames={{ messageBubbleSender: "rounded-2xl" }} features={{ showPhoneCall: true, onPhoneCall: ({ conversationId }) => startCall(conversationId), }} />

import { defaultChatLayoutConfig } from "@realtimexsco/live-chat"; export const chatLayoutConfig = { ...defaultChatLayoutConfig, // sidebar: true, // left panel wrapper // loggedUserDetails: true, // profile + new chat button // channelList: true, // conversation list // header: true, // channel header bar // messageList: true, // message bubbles // input: true, // composer // forwardModal: true, // forward dialog };

layout={{ input: false }} // read-only, no composer layout={{ sidebar: false }} // hide sidebar, messages only layout={{ forwardModal: false }} // disable the forward modal layout={{ loggedUserDetails: false, channelList: true }}