@cariosan/react

Pre-built React components + hooks layered on top of @cariosan/client. Use the components if you want chat UI in ten minutes; use the hooks if you want your own UI but the data layer done for you.

pnpm add @cariosan/client @cariosan/react

Provider

Wrap your app once:

import { Cariosan } from "@cariosan/client";
import { ChatProvider } from "@cariosan/react";
import "@cariosan/react/styles.css";
 
const client = new Cariosan({ apiUrl, token });
await client.connect();
 
function App() {
  return (
    <ChatProvider client={client}>
      <ChatUI />
    </ChatProvider>
  );
}

The provider stores the Cariosan instance in context. Components and hooks read it via useCariosan().

Drop-in components

import {
  ChannelList,
  MessageList,
  MessageInput,
  TypingIndicator,
  PresenceBadge,
} from "@cariosan/react";
 
function ChatUI() {
  const [channelId, setChannelId] = useState("order_123");
  return (
    <div className="chat">
      <ChannelList
        selectedId={channelId}
        onSelect={(ch) => setChannelId(ch.externalId)}
      />
      <section>
        <MessageList channelId={channelId} />
        <TypingIndicator channelId={channelId} />
        <MessageInput channelId={channelId} />
      </section>
    </div>
  );
}

Hooks

Use these when you want custom UI but don't want to re-implement subscription plumbing:

import {
  useChannels,
  useMessages,
  useMessageActions,
  useMessageSender,
  useTyping,
  usePresence,
  useConnectionStatus,
} from "@cariosan/react";
 
function CustomRoom({ channelId, myUserId }: { channelId: string; myUserId: string }) {
  const { connected } = useConnectionStatus();
  // Pass currentUserId so live reaction events set `reacted_by_me`.
  const { messages, hasMore, loadMore } = useMessages(channelId, { currentUserId: myUserId });
  const { typingUsers } = useTyping(channelId);
  const { sendMessage, sending } = useMessageSender(channelId);
  const { addReaction, removeReaction, editMessage, deleteMessage } = useMessageActions(channelId);
 
  return /* your UI */;
}

Every hook handles subscribe / unsubscribe on the underlying Channel automatically — no cleanup code in your components.

useMessages keeps its list live for reactions, edits, and unsends too: each Message exposes reactions ([{ emoji, count, reacted_by_me }]), edited_at, and deleted_at, updated in place as events arrive. useMessageActions(channelId) returns { addReaction, removeReaction, editMessage, deleteMessage } bound to the channel, and the built-in MessageList already renders reaction pills, an “(edited)” marker, and deleted-message tombstones.

Quoted replies

Send a reply by passing parentId to useMessageSender's sendMessage:

await sendMessage({ text: "On it!", parentId: original.id });

Each reply Message carries parent_id and a quoted_message preview ({ id, user_id, user_name, content, type, deleted }). The built-in MessageList renders that quote above the reply automatically — and shows "Original message was deleted" when the quoted parent has been unsent. See Quoted replies.

For the built-in compose flow (a "Reply" button on each bubble → a quote chip above the input → send), wrap the room in ReplyDraftProvider:

import { ReplyDraftProvider, MessageList, MessageInput } from "@cariosan/react";
 
function Room({ channelId }: { channelId: string }) {
  return (
    <ReplyDraftProvider>
      <MessageList channelId={channelId} />
      <MessageInput channelId={channelId} />
    </ReplyDraftProvider>
  );
}

With the provider mounted, MessageList shows a Reply action per message, MessageInput shows a cancellable quote chip (Esc clears it), the next send is wired with parentId, and tapping a quote scrolls to the original. Without the provider these affordances stay hidden — the quote rendering on received replies always works regardless. Need finer control? Drive it yourself with useReplyDraft() ({ replyTo, setReplyTo, clearReply }).

Mentions

MessageInput ships an @ autocomplete over channel members. By default it lazily loads the roster via channel.getPresence() the first time you type @; pass mentionMembers to supply the candidate list yourself and skip the round-trip:

<MessageInput
  channelId={channelId}
  mentionMembers={[{ external_id: "user_andi", name: "Andi" }]}
/>

Picking a member inserts @Name and sends the resolved external_id in mentions — no fragile text parsing. MessageList highlights mention tokens automatically. For badges, useMentions() tracks live unread-mention counts per channel from the SDK's mention event, and the built-in ChannelList shows a mention dot:

const { counts, total, clear } = useMentions();
// counts["order_123"] → unread mentions in that channel; clear(id) on open.

useMentions accumulates from mount; seed accurate cold-load state from mention_unread_count on GET /v1/me/channels if you need it to survive reloads. See Mentions.

Read receipts

Pass currentUserId to MessageList and your own bubbles get a ✓ / ✓✓ / ✓✓-blue indicator that updates live as members deliver/read:

<MessageList channelId={channelId} currentUserId={myUserId} />

For custom bubbles, useReadReceipts(channelId) seeds the cursors and returns a receiptState(message) that re-renders on every cursor advance:

const { receiptState } = useReadReceipts(channelId);
// receiptState(myMessage) → "sent" | "delivered" | "read"

Delivery is acked automatically by the SDK. If a workspace disables read receipts, ticks never reach blue (delivery still shows). See Read & delivery receipts.

Search

useSearch(channelId?) powers a search box — pass a channelId to scope to one channel, omit it to search across all your channels. The box's styling is yours to provide.

const { results, search, clear, loading } = useSearch(channelId);
 
<input
  onChange={(e) => void search(e.target.value)} // empty input clears
  placeholder="Search messages…"
/>;
// results — relevance-ranked Message[]; loading — in-flight

See Search.

Theming

No Tailwind or CSS-in-JS. Override CSS variables on any ancestor:

.my-chat {
  --cariosan-primary: #e11d48;
  --cariosan-radius: 4px;
}

Full variable list:

:root {
  --cariosan-primary: #10B981;
  --cariosan-primary-contrast: #FFFFFF;
  --cariosan-bg: #FFFFFF;
  --cariosan-surface: #F3F4F6;
  --cariosan-text: #111827;
  --cariosan-text-muted: #6B7280;
  --cariosan-border: #E5E7EB;
  --cariosan-radius: 8px;
  --cariosan-spacing-xs: 4px;
  --cariosan-spacing-sm: 8px;
  --cariosan-spacing-md: 12px;
  --cariosan-spacing-lg: 16px;
  --cariosan-font: system-ui, sans-serif;
}

Bundle size

Measured against the current dist/ build (pnpm build && gzip -c dist/index.js | wc -c):

• @cariosan/react: 2.6 KB gzipped (6.8 KB raw)
• @cariosan/react/styles.css: 1.2 KB gzipped (4.2 KB raw)
• @cariosan/client (peer): 3.0 KB gzipped (8.6 KB raw)

React + React DOM are peer dependencies, so they don't count toward the SDK weight. A complete React + Cariosan client + UI bundle lands around 51 KB gzipped including React 18.

Missing a component?

The hooks cover every data surface the components use. If your design requires something we haven't built (a sidebar, a search bar, channel settings), build it with the hooks — no need to eject.