Skip to content
Komozu Docs

@komozu/react

React components for Komozu, the chat for the signed-in users of your website or app. Same chat as the embed script, without an iframe.

Terminal window
npm install @komozu/react

The chat in one line

Section titled “The chat in one line”

KomozuChat needs your publishable key (dashboard → API keys), a channel and the signed-in member’s token. No integration to create: the default look is the same everywhere, and each setting is a prop.

import { KomozuChat } from '@komozu/react';
import '@komozu/react/fonts'; // optional: self-hosted fonts of the Komozu theme


<KomozuChat clientId="kz_live_…" channel="general" token={user?.komozuToken ?? null} />

Default look: inline in the page, card surface, auto height (up to 600 px), the project color (project Settings), light or dark following the visitor’s system (visitors can switch from the chat). Images and videos follow the channel’s setting.

Prop
clientIdPublishable key (kz_live_…), required
channelChannel slug (or UUID), or { externalId: '…' } for a channel your backend created with that id. Required
tokenThe signed-in member’s token, stored by your server when it created the member (Identify your users). Without it, or null after a sign-out, the chat only asks to sign in on your site: no message, no input
layoutinline (default) or floating (bubble in a bottom corner)
surfacecard (default) or blend (melts into your page)
primaryColor#RRGGBB; default: the project color (null = Komozu palette)
themeModeauto (default), light, dark
heightauto (default) or a number of pixels (inline)
maxHeightMaximum height in auto mode (default 600)
positionbottom-right (default) or bottom-left (bubble)
title, radiusChat title; corner radius none, sm, md, lg, full
localeen or fr; default: the visitor’s browser language
tokenProviderOptional: a function that returns the token (wins over token)
apiUrlDefaults to https://api.komozu.com

No member token, unknown channel, refused domain, private channel, banned member or refused token: the component shows a short, sober status screen instead of failing silently.

Pinned messages and channel admins

Section titled “Pinned messages and channel admins”

Nothing to set up: the chat shows the latest pinned message at the top, and a button opens the list of pinned messages in a panel that slides inside the chat (it fits a small iframe and the floating bubble). A click on a pinned message goes back to the conversation and scrolls to it, loading older messages if needed.

When the signed-in member is admin of the channel (dashboard, or channels.setRole), the chat shows the Admin badge next to their name and, in the ⋯ menu of each message: pin / unpin, delete and remove a member (private channels). Deleting and removing ask for a confirmation drawn in the chat. A role change applies to the open chat right away; the API checks every action.

Reporting a message

Section titled “Reporting a message”

Every member can report a message from its ⋯ menu (any message but their own, admins’ included). A short confirmation drawn in the chat offers an optional reason (spam, harassment, inappropriate, other); then the chat thanks the reader and the action turns to “Reported”. The project owner finds the message in the dashboard’s Reports page and gets an email. Nothing identifies who reported it.

Message menu and editing

Section titled “Message menu and editing”

The ⋯ button sits right next to each bubble (on hover, always visible on touch screens) and opens the message’s actions just below it: Edit on your own messages, Report, and the admin actions. Editing turns the bubble into a field (Enter saves, Shift+Enter adds a line, Escape cancels); an edited message shows “edited” for everyone. A member edits their own messages with no time limit.

One channel per event

Section titled “One channel per event”

Your backend creates a channel per event with your own id (@komozu/node), and each event page shows its channel:

<KomozuChat clientId="kz_live_…" channel={{ externalId: `evt_${event.id}` }} token={user.komozuToken} />

The channel must belong to the project of the key; its access level and the project’s allowed domains apply as usual.

A bubble with your colors

Section titled “A bubble with your colors”
<KomozuChat clientId="kz_live_…" channel="support" token={user.komozuToken} layout="floating" position="bottom-left" primaryColor="#047857" />

Language

Section titled “Language”

Texts (buttons, statuses, errors) are in English or French. Default: the visitor’s browser language (French for fr, fr-CA…, English otherwise). Force it with locale="fr" on KomozuChat or KomozuProvider, or wrap standalone components in KomozuLocaleProvider. useKomozuMessages() returns the texts of the current language.

Lower-level building blocks

Section titled “Lower-level building blocks”
import { KomozuProvider, ChatBox, ChatWidget } from '@komozu/react';


<KomozuProvider options={{ apiUrl: 'https://api.komozu.com', clientId: 'kz_live_…', memberToken: user?.komozuToken }} theme={{ surface: 'card' }} locale="fr">
  <ChatBox channelId="u15" height="auto" maxHeight={600} />      {/* inline */}
  <ChatWidget channelId="u15" position="bottom-right" />          {/* floating bubble */}
</KomozuProvider>
  • ChatBox is the single chat component used by every mode (inline card / blend, floating panel). It shows one channel; showChannelSwitcher (default false) lists the project’s readable channels for apps that navigate between several.
  • “Powered by komozu” follows the project’s plan: always shown on Free, hidden on Starter and Pro. On a paid plan, <ChatBox showPoweredBy /> shows it again; on Free, showPoweredBy={false} has no effect.
  • Hooks: useKomozu, useChannel, useMessages, useTyping, useChannels, useChannelLookup, useKomozuMessages, useChannelAdmin (reader’s role, pinned messages, admin actions), useMessageReport (Report: confirmation, reason, thank-you), useMessageEdit (editing your own messages).
  • Pieces: MessageList / MessageItem (optional actions next to the bubble and editor in its place), MessageInput, ChatHeader, ChatStatusScreen, AttachmentPreview, AuthorBadge (admin: channel admins and the project owner), PinnedBanner, PinnedPanel, MessageActionMenu (the ⋯ menu), MessageActions (Edit, Report, plus the admin actions), MessageEditor, ChatConfirmDialog, ReportReasonPicker…
  • Theming: CSS variables --komozu-* on the root (KomozuThemeRoot), light and dark. Any kz-* class can be restyled with plain CSS.

Preview without a server

Section titled “Preview without a server”

@komozu/react/preview runs the real chat with no network and no account: sample history, a pinned message, and what you send is echoed back on the page only (nothing is published). Useful for design reviews and UI tests. Pass PREVIEW_MEMBER_TOKEN as the member token: without a token, the chat only asks to sign in.

import { KomozuProvider, ChatBox, MemoryStorage } from '@komozu/react';
import { createPreviewFetch, PREVIEW_MEMBER_TOKEN } from '@komozu/react/preview';


const options = {
  apiUrl: 'https://preview.komozu.local',
  clientId: 'preview',
  storage: new MemoryStorage(),
  memberToken: PREVIEW_MEMBER_TOKEN,
  fetch: createPreviewFetch({
    live: [{ author: { member: 'Night Owl' }, content: 'Anyone here?', delayMs: 3000 }],
  }),
};


<KomozuProvider options={options}>
  <ChatBox channelId="general" />
</KomozuProvider>

createPreviewFetch options: history (messages already in #general), live (messages that arrive after delayMs, each preceded by the typing indicator, played once), attachmentsEnabled (default true), viewerName (name of your own messages, default You).

Guides

Section titled “Guides”