React Realtime Hooks (totalum-sdk/react)

import … from 'totalum-sdk/react' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

The browser side of realtime rooms for React client components: useRealtimeChannel(room) connects to a room, keeps the messages received, shows who else is present, and reconnects by itself (every deploy drops sockets). The page never holds a key: it asks your own server route for a ticket (default POST /api/realtime/ticket), which calls totalum.realtime.ticket. RealtimeChannel is the same thing without React.

'use client';
import { useRealtimeChannel } from 'totalum-sdk/react';
const { messages, publish } = useRealtimeChannel('chat:team-1');

#useRealtimeChannel

useRealtimeChannel(room: string, options?: RealtimeChannelOptions): { publish, status, messages, others }

Joins a realtime room from a React client component and re-renders on every message: status, the messages received since it opened, others (with presence), and publish(data, event?). It asks your route for a ticket (POST /api/realtime/ticket with { room }, which calls totalum.realtime.ticket after your auth check), opens the socket, and re-tickets and reconnects with backoff after every drop. Render status === 'reconnecting' as an ordinary state, not an error. The options of the first render are kept; a new room opens a new connection.

Parameters

Returns { publish, status, messages, others } — The room's snapshot (status, messages, others) and publish(data, event?), which sends to everyone in the room (you included) and returns false when the socket is not open.

Example

'use client';
import { useRealtimeChannel } from 'totalum-sdk/react';

export function Chat({ teamId, name }: { teamId: string; name: string }) {
  const { messages, others, publish, status } = useRealtimeChannel(`chat:${teamId}`, { presence: { name } });
  return (
    <div>
      <p>{status === 'open' ? `${others.length} others online` : 'Connecting…'}</p>
      {messages.map((m) => <p key={m.id}><b>{m.identity.name}</b>: {String(m.data)}</p>)}
      <button onClick={() => publish('Hello!')}>Say hello</button>
    </div>
  );
}

Result:

{
  status: 'open',
  messages: [{ id: '5f0c…', event: 'message', identity: { id: 'user_7', name: 'Bob' }, data: 'Hello!', ts: '2026-10-11T18:02:11.204Z' }],
  others: [{ connectionId: '1b9e…', identity: { id: 'user_7', name: 'Bob' }, meta: { name: 'Bob' } }],
  publish: [Function]
}

#RealtimeChannel

One room over one socket, without React (Vue, Svelte, plain scripts): connect(), read getSnapshot(), listen with subscribe(), send with publish(), close() when done. It re-tickets and reconnects by itself after a drop. useRealtimeChannel is a thin React wrapper over it.

Example

import { RealtimeChannel } from 'totalum-sdk/react';

const channel = new RealtimeChannel('chat:team-1', { presence: { name: 'Ana' } });
channel.subscribe(() => render(channel.getSnapshot()));
channel.connect();
channel.publish({ text: 'Hello' });
// later
channel.close();

#RealtimeChannelOptions

How useRealtimeChannel / RealtimeChannel get their ticket, announce presence and keep messages.

#RealtimeMessage

One message received in a room.

#RealtimePeer

Another connection present in the room (with the presence option).

#RealtimeSnapshot

The current state of a room: what useRealtimeChannel returns (plus publish), and RealtimeChannel.getSnapshot().

#RealtimeStatus

The state of a room's connection: connecting (first ticket and socket), open, reconnecting (after a drop — every deploy drops sockets — show it as an ordinary state, not an error) or closed (after close() or unmount).