Package Reference
Hooks Documentation
All hooks are available from the package root and must be used inside a Chat / ChatMain provider tree.
useChatStore
Zustand store selector hook. Access any slice of chat state or any store action.
| Parameter | Return value | Notes |
|---|---|---|
| selector: (state) => T | T — the selected slice of state | Re-renders only when the selected value changes |
import { useChatStore } from "@realtimexsco/live-chat";
const conversations = useChatStore((s) => s.conversations);
const emitDmSend = useChatStore((s) => s.emitDmSend);
const allUsers = useChatStore((s) => s.allUsers);
const manageGroupMembers = useChatStore((s) => s.manageGroupMembers);
const loggedUserDetails = useChatStore((s) => s.loggedUserDetails);useChatController
Provides the state and handlers needed to build a fully custom ChatLayout. See Replace entire UI.
| Return value | Description |
|---|---|
| activeChannel | The currently selected conversation/channel object |
| conversationId | Id of the active conversation |
| conversationMessages | Messages loaded for the active conversation |
| handleChannelSelect | Selects a channel and loads its messages |
| handleSendMessage | Sends a message in the active conversation |
| setActiveChannel | Manually sets the active channel |
| state / updateState | Internal UI state and its setter |
const {
activeChannel,
conversationId,
conversationMessages,
handleChannelSelect,
handleSendMessage,
setActiveChannel,
state,
updateState,
} = useChatController();useChatContext
Low-level access to the raw chat provider context — mainly useful for advanced integrations that need values not exposed by useChatController. Prefer controller or store hooks for normal UI work.
import { useChatContext } from "@realtimexsco/live-chat";
const ctx = useChatContext();
// Inspect provider values for diagnostics — avoid coupling UI deeply to this APIuseChatCustomization / useChatCustomizationOptional
Reads the currently merged components and classNames configuration inside custom child components. Use this when a slot needs to know which overrides are active. The Optional variant returns undefined instead of throwing when used outside a provider.
import {
useChatCustomization,
useChatCustomizationOptional,
} from "@realtimexsco/live-chat";
const { components, classNames } = useChatCustomization();
const maybe = useChatCustomizationOptional(); // undefined outside ChatMainuseChatFeatures / useChatFeaturesOptional
Reads the current phone/video call flags and their callbacks (showPhoneCall, showVideoCall, onPhoneCall, onVideoCall). Useful inside a custom HeaderCallActions slot.
import { useChatFeatures } from "@realtimexsco/live-chat";
const { showPhoneCall, showVideoCall, onPhoneCall, onVideoCall } =
useChatFeatures();useChatTheme
Returns themeColor, isDark, and the resolved CSS variables driving the brand accent. Use this when a custom component must match the active chat theme without hard-coding colors.
import { useChatTheme } from "@realtimexsco/live-chat";
const { themeColor, isDark } = useChatTheme();useChatLocale
Formats dates and times using the active locale, timeZone, and hour12 setting passed to ChatMain. Prefer this over ad-hoc Intl calls so timestamps stay consistent across slots.
import { useChatLocale } from "@realtimexsco/live-chat";
const { formatDateTime, locale, timeZone, hour12 } = useChatLocale();
const label = formatDateTime(message.createdAt);useChatAlerts
Reads and controls the current error/info alert bar state shown above the chat shell. Use it to surface API failures or clear banners after recovery.
import { useChatAlerts } from "@realtimexsco/live-chat";
const { alert, showAlert, clearAlert } = useChatAlerts();
showAlert({ type: "error", message: "Could not load messages" });