useWebSocket

Hook for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.

See: WebSocket API.

Types

UseWebSocketProps

• @template T Type of the data exchanged on the socket.

Props for the useWebSocket.

Property	Type	Required	Description
url	string \| URL		WebSocket endpoint URL. Can be set here or passed to open() at connection time.
protocols	string \| string[]		Sub-protocol string or array of strings forwarded to the WebSocket constructor.
binaryType	"blob" \| "arraybuffer"		The binary data type used to receive binary messages.
immediateConnection	boolean		When true, the WebSocket connection is opened immediately on mount.
onOpen	(evt: Event) => void		Called when the WebSocket connection opens.
onMessage	(data: T, evt: MessageEvent<T>) => void		Called when a message is received.
onError	(evt: Event, err?: Error) => void		Called when a WebSocket error occurs.
onClose	(evt: CloseEvent) => void		Called when the WebSocket connection closes.
bufferingData	boolean		When true, messages sent while the connection is not yet open are buffered and delivered once the connection is established.
reconnect	boolean \| { retries: number; delay: number; onFailed?: () => void }		Auto-reconnect configuration. - true — reconnect indefinitely with the default delay. - { retries, delay, onFailed? } — reconnect up to retries times with delay ms between attempts.
parser	"json" \| "text" \| "blob" \| "arraybuffer" \| ((data: string \| ArrayBuffer \| Blob) => unknown)		Message parser applied to incoming MessageEvent.data before calling onMessage. - "json" — JSON.parse. - "text" — identity (string passthrough). - "blob" / "arraybuffer" — return the raw binary data. - A function — custom parser receiving the raw data and returning the typed value.

UseWebSocketResult

• @template T Type of the data exchanged on the socket.

Result object returned by useWebSocket.

Property	Type	Required	Description
status	"READY" \| "CONNECTING" \| "CONNECTED" \| "RECONNECTING" \| "DISCONNECTING" \| "DISCONNECTED"	✓	Current connection state. - "READY" — not yet connected. - "CONNECTING" — connection in progress. - "CONNECTED" — connection established. - "RECONNECTING" — attempting to reconnect after a disconnect. - "DISCONNECTING" — close handshake in progress. - "DISCONNECTED" — connection fully closed.
data	T \| null	✓	Most recently received parsed message data. null before the first message.
lastMessage	MessageEvent \| null	✓	The raw MessageEvent for the most recently received message. null before the first message.
open	(url?: string \| URL) => void	✓	Open the WebSocket connection.
send	(data: string \| ArrayBuffer \| Blob \| TypedArray) => void	✓	Send raw data over the WebSocket.
sendJSON	(data: unknown) => void	✓	Serialise a value as JSON and send it over the WebSocket.
close	(code?: number, reason?: string) => void	✓	Close the WebSocket connection.
reconnect	() => void	✓	Manually trigger a reconnection attempt.
socket	WebSocket \| null	✓	Direct reference to the underlying WebSocket instance. null when not connected.