Skip to main content

​
Overview

The useSocket hook provides access to the Socket.IO client instance and connection state. This is a foundational hook that other hooks use to communicate with the server.

​
Usage

import { useSocket } from '@/hooks/use-socket';

function MyComponent() {
  const { socket, isConnected, isInitialized } = useSocket();
  
  // Use socket to emit events or listen to responses
}

​
Return Value

The hook returns an object with the following properties:
​
socket
Socket | null
The Socket.IO client instance. Will be null until initialized. Once connected, you can use this to emit events and listen for server responses.
// Example: Emit an event
socket?.emit('join-room', { roomId: 'ABC123', userName: 'John' });

// Example: Listen for events
socket?.on('room-joined', (data) => {
  console.log('Joined room:', data.room.id);
});
​
isConnected
boolean
Whether the socket is currently connected to the server. Use this to show connection status or disable features when disconnected.
{isConnected ? (
  <span className="text-green-500">Connected</span>
) : (
  <span className="text-red-500">Disconnected</span>
)}
​
isInitialized
boolean
Whether the socket has been initialized. This becomes true once the SocketProvider mounts on the client side.

​
Implementation Details

The useSocket hook is a simple wrapper around React Context:
src/hooks/use-socket.ts
export function useSocket() {
  return useSocketContext();
}
The actual Socket.IO instance is managed by the SocketProvider context provider, which:
  1. Creates a Socket.IO client connection to /api/socket/io
  2. Manages connection state (connected/disconnected)
  3. Handles automatic reconnection
  4. Provides the socket instance to all child components

​
Socket Configuration

The socket is configured with these settings:
src/contexts/socket-provider.tsx:46-50
const socketInstance = io(socketUrl, {
  path: '/api/socket/io',
  transports: ['websocket', 'polling'],
  autoConnect: true,
});
  • path: Custom Socket.IO server path
  • transports: Prefer WebSocket, fall back to polling
  • autoConnect: Automatically connect when created

​
Socket Provider Setup

The useSocket hook must be used within a SocketProvider. Watch N Chill sets this up in the root layout:
src/app/layout.tsx
import { SocketProvider } from '@/contexts/socket-provider';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SocketProvider>
          {children}
        </SocketProvider>
      </body>
    </html>
  );
}
If you call useSocket outside of a SocketProvider, it will throw an error: “useSocket must be used within a SocketProvider”

​
Connection Lifecycle

The socket goes through these states:
  1. Not initialized (isInitialized: false, socket: null) - Before SocketProvider mounts
  2. Initialized, connecting (isInitialized: true, isConnected: false, socket: Socket) - Socket created, attempting connection
  3. Connected (isInitialized: true, isConnected: true, socket: Socket) - Successfully connected to server
  4. Disconnected (isInitialized: true, isConnected: false, socket: Socket) - Connection lost, will auto-reconnect

​
Example: Custom Event Listener

import { useSocket } from '@/hooks/use-socket';
import { useEffect, useState } from 'react';

function RoomStatus() {
  const { socket, isConnected } = useSocket();
  const [userCount, setUserCount] = useState(0);
  
  useEffect(() => {
    if (!socket) return;
    
    // Listen for user count updates
    socket.on('user-count-changed', ({ count }) => {
      setUserCount(count);
    });
    
    // Cleanup listener on unmount
    return () => {
      socket.off('user-count-changed');
    };
  }, [socket]);
  
  if (!isConnected) {
    return <div>Connecting...</div>;
  }
  
  return <div>{userCount} users in room</div>;
}
  • useRoom - Built on useSocket, manages room state and membership
  • useVideoSync - Built on useSocket, handles video synchronization
  • useCreateRoom - Uses useSocket to create rooms
  • useJoinRoom - Uses useSocket to join rooms

​
Socket.IO Events

See the Socket.IO Events documentation for all available events:

Room Events

Create, join, and manage rooms

Video Events

Control synchronized video playback

Chat Events

Send messages and typing indicators

Build docs developers (and LLMs) love

Get started for freeTalk to us