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 · useWebSocketEditor
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.tsfor implementation details