Network & RealtimeAdvancedSSR-safehooks/network/useWebSocket.ts

useWebSocket

WebSocket with reconnect.

Import

TypeScript
import { useWebSocket } from '@/hooks';

API

Signature

useWebSocket(url, options?) → { status, send, connect, disconnect, ... }

When to use

Live dashboards, chat, collaborative cursors.

SSR / Next.js

Connect only in the browser / Client Components.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useWebSocket
Editor
function LiveFeed() {
  const { status, lastMessage, send, connect, disconnect } = useWebSocket(
    process.env.NEXT_PUBLIC_WS_URL,
    { reconnect: true },
  );

  return (
    <div>
      <p>Status: {status}</p>
      <pre>{lastMessage?.data?.toString()}</pre>
      <button onClick={() => send(JSON.stringify({ type: 'ping' }))}>Ping</button>
      <button onClick={connect}>Connect</button>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}
Preview

Implementation source

Full library source for useWebSocket — copy into your project when you are not installing a package yet.

hooks/network/useWebSocket.ts
import { useCallback, useEffect, useRef, useState } from 'react';
import type { ConnectionStatus } from '../types';
import { isBrowser } from '../utility/isBrowser';
import { useLatest } from '../utility/useLatest';

export interface UseWebSocketOptions {
  protocols?: string | string[];
  /** @default true */
  autoConnect?: boolean;
  /** @default true */
  reconnect?: boolean;
  reconnectIntervalMs?: number;
  maxRetries?: number;
  onOpen?: (event: Event) => void;
  onClose?: (event: CloseEvent) => void;
  onError?: (event: Event) => void;
  onMessage?: (event: MessageEvent) => void;
}

export interface UseWebSocketReturn {
  status: ConnectionStatus;
  lastMessage: MessageEvent | null;
  send: (data: string | ArrayBufferLike | Blob | ArrayBufferView) => void;
  connect: () => void;
  disconnect: () => void;
  retryCount: number;
}

/**
 * WebSocket client with reconnect, status, and cleanup.
 * Pass the full WebSocket URL; never hardcode endpoints in the hook.
 */
export function useWebSocket(
  url: string | null | undefined,
  options: UseWebSocketOptions = {},
): UseWebSocketReturn {
  const {
    protocols,
    autoConnect = true,
    reconnect = true,
    reconnectIntervalMs = 2000,
    maxRetries = Infinity,
    onOpen,
    onClose,
    onError,
    onMessage,
  } = options;

  const [status, setStatus] = useState<ConnectionStatus>('closed');
  const [lastMessage, setLastMessage] = useState<MessageEvent | null>(null);
  const [retryCount, setRetryCount] = useState(0);
  const wsRef = useRef<WebSocket | null>(null);
  const manualClose = useRef(false);
  const retryTimer = useRef<ReturnType<typeof setTimeout> | null>(null);

  const onOpenRef = useLatest(onOpen);
  const onCloseRef = useLatest(onClose);
  const onErrorRef = useLatest(onError);
  const onMessageRef = useLatest(onMessage);

  const clearRetry = () => {
    if (retryTimer.current) {
      clearTimeout(retryTimer.current);
      retryTimer.current = null;
    }
  };

  const disconnect = useCallback(() => {
    manualClose.current = true;
    clearRetry();
    wsRef.current?.close();
    wsRef.current = null;
    setStatus('closed');
  }, []);

  const connect = useCallback(() => {
    if (!isBrowser() || !url) return;
    manualClose.current = false;
    clearRetry();
    wsRef.current?.close();
    setStatus('connecting');
    const ws = protocols
      ? new WebSocket(url, protocols)
      : new WebSocket(url);
    wsRef.current = ws;

    ws.onopen = (event) => {
      setStatus('open');
      setRetryCount(0);
      onOpenRef.current?.(event);
    };
    ws.onmessage = (event) => {
      setLastMessage(event);
      onMessageRef.current?.(event);
    };
    ws.onerror = (event) => {
      setStatus('error');
      onErrorRef.current?.(event);
    };
    ws.onclose = (event) => {
      setStatus('closed');
      onCloseRef.current?.(event);
      wsRef.current = null;
      if (!manualClose.current && reconnect) {
        setRetryCount((count) => {
          if (count >= maxRetries) return count;
          retryTimer.current = setTimeout(() => {
            connect();
          }, reconnectIntervalMs);
          return count + 1;
        });
      }
    };
  }, [
    url,
    protocols,
    reconnect,
    reconnectIntervalMs,
    maxRetries,
    onOpenRef,
    onCloseRef,
    onErrorRef,
    onMessageRef,
  ]);

  const send = useCallback(
    (data: string | ArrayBufferLike | Blob | ArrayBufferView) => {
      if (wsRef.current?.readyState === WebSocket.OPEN) {
        wsRef.current.send(data);
      }
    },
    [],
  );

  useEffect(() => {
    if (autoConnect && url) connect();
    return () => {
      manualClose.current = true;
      clearRetry();
      wsRef.current?.close();
      wsRef.current = null;
    };
  }, [url, autoConnect]);

  return { status, lastMessage, send, connect, disconnect, retryCount };
}

Copy-paste example

useWebSocket.example.tsx
'use client';

import { useWebSocket } from '@/hooks';

export function LiveFeed() {
  const { status, lastMessage, send, connect, disconnect } = useWebSocket(
    process.env.NEXT_PUBLIC_WS_URL,
    { reconnect: true },
  );

  return (
    <div>
      <p>Status: {status}</p>
      <pre>{lastMessage?.data?.toString()}</pre>
      <button onClick={() => send(JSON.stringify({ type: 'ping' }))}>Ping</button>
      <button onClick={connect}>Connect</button>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Never hardcode URLs in components shared across envs — use env vars.
  • Source of truth: open hooks/network/useWebSocket.ts for implementation details