React SDK

React SDK

Complete API reference for @realtime-sdk/react.

RealtimeProvider

Provides the Realtime client context to your app.

import { RealtimeProvider } from '@realtime-sdk/react';
 
<RealtimeProvider
  endpoint="wss://api.realtimesdk.dev"
  authToken={getToken}
  // Optional
  heartbeatInterval={30000}
  heartbeatTimeout={10000}
  maxReconnectAttempts={10}
  debug={false}
>
  {children}
</RealtimeProvider>

Props

Prop	Type	Default	Description
endpoint	string	Required	WebSocket server URL
authToken	string | () => string | () => Promise<string>	Required	JWT auth token
heartbeatInterval	number	30000	Ping interval (ms)
heartbeatTimeout	number	10000	Pong timeout (ms)
maxReconnectAttempts	number	10	Max reconnect tries (-1 for infinite)
debug	boolean	false	Enable debug logging

useRoom

Access or create a room.

const room = useRoom('room-id');

Returns

Property	Type	Description
id	string	Room ID
status	RoomStatus	'joining' | 'joined' | 'leaving' | 'left' | 'error'
join(options?)	() => Promise<void>	Join the room
leave()	() => void	Leave the room
on(event, callback)	() => () => void	Subscribe to events

usePresence

Track users in a room.

const { users, self, others, updatePresence } = usePresence(room);

Returns

Property	Type	Description
users	PresenceUser[]	All users in room
self	PresenceUser | null	Current user
others	PresenceUser[]	Other users
updatePresence(data)	(data: Partial<T>) => void	Update your presence

PresenceUser

interface PresenceUser {
  id: string;
  color: string;
  data: PresenceData;
  cursor: CursorPosition | null;
}

useCursors

Track cursor positions.

const { cursors, updateCursor } = useCursors(room, { throttle: 50 });

Options

Option	Type	Default	Description
throttle	number	50	Update throttle (ms)

Returns

Property	Type	Description
cursors	CursorInfo[]	All visible cursors
updateCursor(position)	(pos: CursorPosition | null) => void	Update your cursor

CursorInfo

interface CursorInfo {
  id: string;
  name?: string;
  color: string;
  position: { x: number; y: number };
}

useDocument

Collaborative document sync with Yjs.

const { doc, awareness, synced, status, pendingChanges, provider } = useDocument(room, 'doc-id');

Returns

Property	Type	Description
doc	Y.Doc	Yjs document
awareness	Awareness	Yjs awareness instance
synced	boolean	Initial sync complete
status	'connected' | 'disconnected'	Document provider status
pendingChanges	number	Local updates queued while disconnected
provider	DocumentProvider	Compatibility provider for editor integrations

useBroadcast

Send custom events to the room.

const { broadcast, on } = useBroadcast(room);
 
// Send
broadcast('reaction', { emoji: '👍' });
 
// Receive
useEffect(() => {
  return on('reaction', ({ senderId, data }) => {
    console.log(`${senderId} reacted with ${data.emoji}`);
  });
}, [on]);

useConnectionStatus

Monitor connection state.

const status = useConnectionStatus();
// 'connecting' | 'connected' | 'disconnected' | 'reconnecting'