Access the raw SocketClient instance and current connection state.

const {
  client,            // SocketClient | null
  isConnected,       // boolean
  isAuthenticated,   // boolean
  connectionState,   // ConnectionState enum
  userId,            // string | null
} = useSocket();

Subscribe to any socket event. Automatically unsubscribes on component unmount. Handler is called with the event payload.

useSocketEvent('message', (data) => {
  console.log('New message from', data.from, ':', data.content);
});

useSocketEvent('user_online', ({ userId }) => {
  setOnlineUsers(prev => new Set(prev).add(userId));
});

Collects all incoming direct messages into a local array. Listens for the message event automatically.

const {
  messages,     // Array<{ id, from, content, timestamp, metadata? }>
  addMessage,   // (message) => void — manually add a message
  clearMessages // () => void — clear all messages
} = useMessages();

Send direct messages with loading and error state. isSending resets when message_delivered or message_error is received.

const {
  sendMessage, // (to: string, content: string, metadata?) => void
  isSending,   // boolean
  error,       // string | null
} = useSendMessage();

// Usage
sendMessage('user-456', 'Hello!');
sendMessage('user-456', 'With metadata', { priority: 'high' });

Track online/offline status. Maintains a Set of online user IDs, updated from user_online, user_offline, and online_status events.

const {
  onlineUsers,      // Set<string> — set of online userIds
  isUserOnline,     // (userId: string) => boolean
  checkOnlineStatus // (userIds: string[]) => void — triggers online_status event
} = usePresence();

// Check if a user is online
if (isUserOnline('user-123')) {
  console.log('User is online');
}

// Bulk check
checkOnlineStatus(['user-1', 'user-2', 'user-3']);

For direct message conversations. Tracks who is typing. Typing indicators auto-clear after typingTimeout ms (default: 3000) if no stop event is received.

const {
  startTyping, // (to: string) => void
  stopTyping,  // (to: string) => void
  usersTyping, // Set<string> — userIds currently typing
} = useTypingIndicator(3000);

// In a chat input
<input
  onFocus={() => startTyping(recipientId)}
  onBlur={() => stopTyping(recipientId)}
  onChange={() => startTyping(recipientId)}
/>

// Display
{[...usersTyping].map(id => (
  <span key={id}>{id} is typing...</span>
))}

Manages membership state for a single group. Keeps the members list in sync by listening to group_member_joined and group_member_left events. Automatically fetches members once joined.

const {
  group,          // Group | null — full group object
  members,        // GroupMember[] — current member list
  isJoined,       // boolean
  join,           // () => void — emit group_join
  leave,          // () => void — emit group_leave
  refreshMembers, // () => void — re-fetch members from server
} = useGroup('group-id-123');

// Usage
if (!isJoined) join();
console.log(group?.name, 'has', members.length, 'members');

Manages messages for a single group. Auto-fetches history on mount. Handles queued messages from the group_joined payload. Deduplicates by message ID on reconnect replay.

const {
  messages,         // GroupMessage[] — sorted by timestamp
  isLoadingHistory, // boolean
  sendMessage,      // (content, metadata?) => void
  markRead,         // (messageId) => void
  fetchHistory,     // (before?: number) => void — load older messages
  clearMessages,    // () => void
} = useGroupMessages('group-id-123', {
  fetchHistory: true, // auto-fetch on mount (default: true)
  limit: 50,          // messages per page (default: 50)
});

// Paginate older messages
fetchHistory(messages[0]?.timestamp); // pass oldest timestamp as 'before'

Tracks typing indicators for a group. Excludes the local user from typingMembers. startTyping() debounces — calling it repeatedly on each keypress auto-stops after stopDelay ms of inactivity. Stale indicators auto-clear after stopDelay × 2 ms.

const {
  typingMembers, // string[] — userIds currently typing (excludes you)
  startTyping,   // () => void — call on keypress
  stopTyping,    // () => void — call on blur or message send
} = useGroupTyping('group-id-123', 2000);

// In a group chat input
<input
  onKeyDown={startTyping}
  onBlur={stopTyping}
  placeholder="Type a message..."
/>

{typingMembers.length > 0 && (
  <p>{typingMembers.join(', ')} {typingMembers.length === 1 ? 'is' : 'are'} typing...</p>
)}

Returns the authenticated user's group list. Fetches on mount. Auto-updates when groups are created, joined, or left (listens to group_created, group_joined, group_left events).

const {
  groups,      // Group[] — all groups the user belongs to
  isLoading,   // boolean
  refresh,     // () => void — re-fetch from server
  createGroup, // (name, members?, metadata?) => void
} = useUserGroups();

// Create a group
createGroup('Engineering', ['user-2', 'user-3'], { private: true });

// Display groups
groups.map(g => (
  <div key={g.id}>
    {g.name} — {g.members.length} members
  </div>
))

Full WebRTC P2P call lifecycle. Manages RTCPeerConnection, ICE candidate buffering, and local/remote media streams. Supports audio-only or audio+video calls.

const {
  callState,     // CallState — see values below
  incomingCall,  // IncomingCall | null — set when another user calls you
  localStream,   // MediaStream | null
  remoteStream,  // MediaStream | null
  currentCallId, // string | null
  startCall,     // (userId: string) => Promise<void>
  answerCall,    // () => Promise<void> — reads from incomingCall automatically
  rejectCall,    // () => void
  hangUp,        // () => void
} = useVoiceCall({ video: false }); // video: false is the default

// Initiate a call
await startCall('user-456');

// Incoming call — incomingCall is set automatically by the hook
if (incomingCall) {
  // Show UI: incomingCall.from, then:
  await answerCall(); // accepts the call
  // or: rejectCall();
}

Options

CallState

type CallState = 'idle' | 'calling' | 'ringing' | 'active' | 'busy' | 'ended'

SFU-based group conference calling. Handles join/leave, SFU connection lifecycle, and participant tracking. Pass an ISFUClientAdapter instance — use the included LiveKitClientAdapter or implement your own.

import { LiveKitClientAdapter } from 'sockr-client';
// npm install livekit-client  (peer dependency)

const adapter = new LiveKitClientAdapter();

const {
  conferenceState,   // ConferenceState — see values below
  participants,      // ConferenceCallParticipant[] — { userId: string }[]
  activeGroupId,     // string | null
  error,             // string | null
  joinConference,    // (groupId: string) => void
  leaveConference,   // () => void
  onRemoteTrack,     // (handler: (track, participantId) => void) => void
} = useConferenceCall({ adapter, audio: true, video: false });

// Join a group conference
joinConference('group-id-123');

// Handle incoming remote media tracks
onRemoteTrack((track, participantId) => {
  const el = document.getElementById(`video-${participantId}`) as HTMLVideoElement;
  el.srcObject = new MediaStream([track]);
});

ConferenceState

type ConferenceState = 'idle' | 'joining' | 'active' | 'ended' | 'error'

LiveKitClientAdapter

Install the LiveKit client SDK as a peer dependency:

npm install livekit-client

The adapter lazily requires livekit-client at runtime, so it won't affect bundle size if conference calling is unused.

ISFUClientAdapter interface

Implement this to use a different SFU (mediasoup, Janus, etc.):

interface ISFUClientAdapter {
  connect(sfuUrl: string, token: string, opts?: SFUConnectOptions): Promise<void>;
  disconnect(): Promise<void>;
  publishTracks(opts?: SFUPublishOptions): Promise<void>;
  onTrackSubscribed(handler: (track: MediaStreamTrack, participantId: string) => void): void;
  onTrackUnsubscribed(handler: (track: MediaStreamTrack, participantId: string) => void): void;
  onParticipantConnected(handler: (participantId: string) => void): void;
  onParticipantDisconnected(handler: (participantId: string) => void): void;
  onDisconnected(handler: () => void): void;
}