Configuration

Every ChatMain prop, the layout toggles, and the composable Chat provider.

ChatMain props reference

Only clientId, loggedUserDetails and apiUrl are required. Everything else has a sensible default.

Connection & session

Prop	Type	Default	Description
clientId	string	—	Required. Tenant / client id
accessToken	string	—	JWT access token. Omit it to let the package call the client-user login API and create the session itself
refreshToken	string	—	Used to silently get a new accessToken when a request returns 403 “Invalid or expired token”
loggedUserDetails	object	—	Required. { _id, name, email } - _id must match the JWT
apiUrl	string	—	Required. REST API ending with /api/v1
apiVersions	ChatApiVersionConfig	—	API versions after /api, e.g. { v1: "v1", v2: "v2" } (v2 is needed for the unread badge)
socketUrl	string	derived	Socket host (no /api/v1). Defaults to apiUrl without /api/v1
queryParams	Record<string, string \| number \| boolean>	—	Extra query params - see API integration
queryParamApis	ChatApiKey[]	['get']	Which APIs receive queryParams. Default: all GET endpoints
queryParamsByApi	ChatQueryParamsByApi	—	Different query params per API key

Viewport & theme

Prop	Type	Default	Description
viewportHeight	"full" \| "screen" \| string	"full"	Height of the built-in viewport - "screen", a CSS length like "calc(100dvh - 4rem)", or fill the parent
viewportClassName	string	—	Extra classes on the built-in viewport wrapper
themeColor	string	"#7494ec"	Brand accent - hex, named CSS color, rgb/hsl, or var(--token)
fontFamily	string	inherited	CSS font family for the whole chat
fontSize	ChatFontSize	per role	One size (scales every role) or { base, title, subtitle, description }. Numbers mean px
sectionBorderColor	string	theme	Border color of drawer / section list items (--chat-section-border)
sectionBorderRadius	string	theme	Border radius of drawer / section list items, e.g. "8px"
themeTokens	ChatThemeTokens	—	Override any --chat-* design token per mode: { light: {…}, dark: {…} }
colorMode	"light" \| "dark"	—	Controlled color mode (your app owns the theme)
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 in account settings

Details and examples: Themes & locale.

Locale & time

Prop	Type	Default	Description
locale	string	browser	BCP 47 locale, e.g. "en-US"
timeZone	string	browser	IANA time zone, e.g. "Asia/Kolkata"
hour12	boolean	locale	true = 12-hour clock
defaultLocale	string	—	Initial locale when uncontrolled
defaultTimeZone	string	—	Initial time zone when uncontrolled
defaultHour12	boolean	—	Initial 12/24h when uncontrolled
onDateTimePreferencesChange	(prefs) => void	—	The user changed date/time settings
showDateTimeSettings	boolean	true	Show the in-panel date/time button

UI & callbacks

Prop	Type	Default	Description
layout	ChatLayoutConfig	see below	Toggle UI sections
components	ChatComponents	—	Replace UI components (Case 1 & 2)
classNames	ChatClassNames	—	Per-region CSS classes (Case 3)
features	ChatFeatures	—	Phone/video flags, callbacks and call controls
uiConfig	UIConfig	—	Advanced: merged with components / classNames / features
error / info	string \| null	—	Show an error / info banner in the chat panel
onErrorDismiss / onInfoDismiss	() => void	—	Dismiss the banner
onUnreadCountChange	(summary) => void	—	Workspace unread badge - assign, don't accumulate
onSessionEnd	(event) => void	—	An admin ended this session - show your sign-in screen

See Unread badge and Session end & token refresh.

Layout sections (layout prop)

Toggle parts of the default UI without writing components:

typescript

1import { defaultChatLayoutConfig } from "@realtimexsco/live-chat";2 3export const chatLayoutConfig = {4  ...defaultChatLayoutConfig,5  // sidebar: true,           // left panel wrapper6  // loggedUserDetails: true, // profile + new chat button7  // channelList: true,       // conversation list8  // header: true,            // channel header bar9  // messageList: true,       // message bubbles10  // input: true,             // composer11  // forwardModal: true,      // forward dialog12  // threadsInbox: false,     // "Threads" inbox button in the sidebar (off by default)13  // mentions: false,         // "@" Mentions page button in the sidebar (off by default)14};

tsx

1layout={{ input: false }}         // read-only (no composer)2layout={{ sidebar: false }}        // hide the sidebar - messages only3layout={{ forwardModal: false }}   // disable the forward modal4layout={{ loggedUserDetails: false, channelList: true }}  // list without the profile block5layout={{ threadsInbox: true }}    // show the Threads inbox in the sidebar6layout={{ mentions: true }}        // show the Mentions page button in the sidebar

Chat provider (composable mode)

Use Chat + ChatLayout when you need your own page wrapper but not a full ChatMain replacement.

tsx

1"use client";2 3import { Chat, ChatLayout, type ChatComponents } from "@realtimexsco/live-chat";4import { chatConfig } from "@/configs/chat.config";5 6const components: ChatComponents = { Avatar: MyAvatar };7 8export default function ChatPage() {9  return (10    <div className="h-dvh min-h-0 overflow-hidden">11      <Chat12        client={{ id: chatConfig.clientId }}13        accessToken={chatConfig.accessToken}14        loggedUserDetails={chatConfig.loggedUserDetails}15        apiUrl={chatConfig.apiUrl}16        socketUrl={chatConfig.socketUrl}17        themeColor={chatConfig.themeColor}18        uiConfig={{19          components,20          classNames: { sidebar: "bg-slate-900" },21        }}22      >23        <ChatLayout themeColor={chatConfig.themeColor} />24      </Chat>25    </div>26  );27}

Chat provider props

Prop	Type	Required	Description
client	{ id: string }	Yes	Client id
accessToken	string	No	JWT (omit to let the package log in itself)
refreshToken	string	No	Renews accessToken on 403 “expired token”
loggedUserDetails	object	Yes	User profile
apiUrl	string	No	REST base URL
apiVersions	ChatApiVersionConfig	No	API versions after /api
socketUrl	string	No	Socket host
queryParams	ChatQueryParams	No	Shared query params (default target: all GET APIs)
queryParamApis	ChatApiKey[]	No	Which APIs receive queryParams (default ['get'])
queryParamsByApi	ChatQueryParamsByApi	No	Per-API query params
themeColor	string	No	Accent color
uiConfig	UIConfig	No	components, classNames, features
onMessageReceived	(msg) => void	No	Background message callback
onSocketConnected	(id) => void	No	Socket connected
onSocketError	(err) => void	No	Socket error
onUnreadCountChange	(summary) => void	No	Workspace unread badge - assign, don't accumulate
onSessionEnd	(event) => void	No	Admin ended the session - show sign-in
children	ReactNode	Yes	Usually <ChatLayout />

Prop

Type

Default

Description

clientId

string

—

Required. Tenant / client id

accessToken

string

—

JWT access token. Omit it to let the package call the client-user login API and create the session itself

refreshToken

string

—

Used to silently get a new accessToken when a request returns 403 “Invalid or expired token”

loggedUserDetails

object

—

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

apiUrl

string

—

Required. REST API ending with /api/v1

apiVersions

ChatApiVersionConfig

—

API versions after /api, e.g. { v1: "v1", v2: "v2" } (v2 is needed for the unread badge)

socketUrl

string

derived

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

queryParams

Record<string, string | number | boolean>

—

Extra query params - see API integration

queryParamApis

ChatApiKey[]

['get']

Which APIs receive queryParams. Default: all GET endpoints

queryParamsByApi

ChatQueryParamsByApi

—

Different query params per API key

Prop

Type

Default

Description

viewportHeight

"full" | "screen" | string

"full"

Height of the built-in viewport - "screen", a CSS length like "calc(100dvh - 4rem)", or fill the parent

viewportClassName

string

—

Extra classes on the built-in viewport wrapper

themeColor

string

"#7494ec"

Brand accent - hex, named CSS color, rgb/hsl, or var(--token)

fontFamily

string

inherited

CSS font family for the whole chat

fontSize

ChatFontSize

per role

One size (scales every role) or { base, title, subtitle, description }. Numbers mean px

sectionBorderColor

string

theme

Border color of drawer / section list items (--chat-section-border)

sectionBorderRadius

string

theme

Border radius of drawer / section list items, e.g. "8px"

themeTokens

ChatThemeTokens

—

Override any --chat-* design token per mode: { light: {…}, dark: {…} }

colorMode

"light" | "dark"

—

Controlled color mode (your app owns the theme)

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 in account settings

Prop

Type

Default

Description

locale

string

browser

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

timeZone

string

browser

IANA time zone, e.g. "Asia/Kolkata"

hour12

boolean

locale

true = 12-hour clock

defaultLocale

string

—

Initial locale when uncontrolled

defaultTimeZone

string

—

Initial time zone when uncontrolled

defaultHour12

boolean

—

Initial 12/24h when uncontrolled

onDateTimePreferencesChange

(prefs) => void

—

The user changed date/time settings

showDateTimeSettings

boolean

true

Show the in-panel date/time button

Prop

Type

Default

Description

layout

ChatLayoutConfig

see below

Toggle UI sections

components

ChatComponents

—

Replace UI components (Case 1 & 2)

classNames

ChatClassNames

—

Per-region CSS classes (Case 3)

features

ChatFeatures

—

Phone/video flags, callbacks and call controls

uiConfig

UIConfig

—

Advanced: merged with components / classNames / features

error / info

string | null

—

Show an error / info banner in the chat panel

onErrorDismiss / onInfoDismiss

() => void

—

Dismiss the banner

onUnreadCountChange

(summary) => void

—

Workspace unread badge - assign, don't accumulate

onSessionEnd

(event) => void

—

An admin ended this session - show your sign-in screen

Layout sections (layout prop)

Toggle parts of the default UI without writing components:

typescript

1import { defaultChatLayoutConfig } from "@realtimexsco/live-chat";2 3export const chatLayoutConfig = {4  ...defaultChatLayoutConfig,5  // sidebar: true,           // left panel wrapper6  // loggedUserDetails: true, // profile + new chat button7  // channelList: true,       // conversation list8  // header: true,            // channel header bar9  // messageList: true,       // message bubbles10  // input: true,             // composer11  // forwardModal: true,      // forward dialog12  // threadsInbox: false,     // "Threads" inbox button in the sidebar (off by default)13  // mentions: false,         // "@" Mentions page button in the sidebar (off by default)14};

tsx

1layout={{ input: false }}         // read-only (no composer)2layout={{ sidebar: false }}        // hide the sidebar - messages only3layout={{ forwardModal: false }}   // disable the forward modal4layout={{ loggedUserDetails: false, channelList: true }}  // list without the profile block5layout={{ threadsInbox: true }}    // show the Threads inbox in the sidebar6layout={{ mentions: true }}        // show the Mentions page button in the sidebar

Chat provider (composable mode)

Use Chat + ChatLayout when you need your own page wrapper but not a full ChatMain replacement.

tsx

1"use client";2 3import { Chat, ChatLayout, type ChatComponents } from "@realtimexsco/live-chat";4import { chatConfig } from "@/configs/chat.config";5 6const components: ChatComponents = { Avatar: MyAvatar };7 8export default function ChatPage() {9  return (10    <div className="h-dvh min-h-0 overflow-hidden">11      <Chat12        client={{ id: chatConfig.clientId }}13        accessToken={chatConfig.accessToken}14        loggedUserDetails={chatConfig.loggedUserDetails}15        apiUrl={chatConfig.apiUrl}16        socketUrl={chatConfig.socketUrl}17        themeColor={chatConfig.themeColor}18        uiConfig={{19          components,20          classNames: { sidebar: "bg-slate-900" },21        }}22      >23        <ChatLayout themeColor={chatConfig.themeColor} />24      </Chat>25    </div>26  );27}

Prop

Type

Required

Description

client

{ id: string }

Yes

Client id

accessToken

string

JWT (omit to let the package log in itself)

refreshToken

string

Renews accessToken on 403 “expired token”

loggedUserDetails

object

Yes

User profile

apiUrl

string

REST base URL

apiVersions

ChatApiVersionConfig

API versions after /api

socketUrl

string

Socket host

queryParams

ChatQueryParams

Shared query params (default target: all GET APIs)

queryParamApis

ChatApiKey[]

Which APIs receive queryParams (default ['get'])

queryParamsByApi

ChatQueryParamsByApi

Per-API query params

themeColor

string

Accent color

uiConfig

UIConfig

components, classNames, features

onMessageReceived

(msg) => void

Background message callback

onSocketConnected

(id) => void

Socket connected

onSocketError

(err) => void

Socket error

onUnreadCountChange

(summary) => void

Workspace unread badge - assign, don't accumulate

onSessionEnd

(event) => void

Admin ended the session - show sign-in

children

ReactNode

Yes

Usually <ChatLayout />