react-use-websocket

If multiple components pass the same socketUrl to useWebSocket and the share option is set to true, only a single WebSocket will be created. The hook manages subscriptions/unsubscriptions internally. The WebSocket is automatically cleaned up from memory once all subscribers have unmounted or changed their socketUrl.

When sharing, getWebSocket() returns a proxy-wrapped WebSocket that provides controlled access to the underlying shared connection without allowing unsafe behavior.

Instead of a static string, you can pass a function that returns a string or a Promise that resolves to a string as the first argument to useWebSocket.

Important: If the function reference changes, the hook will be called again, which may instantiate a new WebSocket if the returned URL is different. Use useCallback to maintain a stable function reference.

import React, { useCallback } from 'react';
import useWebSocket from 'react-use-websocket';

// In functional React component
const getSocketUrl = useCallback(() => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve('wss://echo.websocket.org');
    }, 2000);
  });
}, []);

const { sendMessage, lastMessage, readyState, getWebSocket } = useWebSocket(
  getSocketUrl,
  STATIC_OPTIONS
);

By default, useWebSocket does not reconnect. To enable reconnection, configure the following options:

1. retryOnError: Set to true to attempt reconnection on error events.
2. shouldReconnect: A callback function (event: CloseEvent) => boolean. If it returns true, the hook attempts to reconnect.
3. reconnectAttempts: The maximum number of reconnection attempts (default is 20).
4. reconnectInterval: The delay between attempts. This can be a number (ms) or a function (attemptNumber: number) => number for advanced strategies like Exponential Backoff.

Exponential Backoff Example:

const [sendMessage] = useWebSocket('wss://echo.websocket.org', {
  shouldReconnect: () => true,
  reconnectAttempts: 10,
  reconnectInterval: (attemptNumber) => Math.min(Math.pow(2, attemptNumber) * 1000, 10000),
});

To use this library in your project, install it via npm or yarn.

Note: If you are using React 18 or newer, install the latest version. If you need to stay on React 16 or 17, install version 3.0.0.

To prevent connection timeouts, you can enable a heartbeat. If heartbeat is enabled, the library sends a 'ping' message at a specified interval. If no response is received within the timeout period, the connection is closed.

Heartbeat Configuration Object:

• message: The string to send as a ping (e.g., 'ping').
• returnMessage: The expected response (e.g., 'pong'). If defined, this response is ignored and will not be set as lastMessage.
• timeout: Time in ms to wait for a response before closing the connection.
• interval: Time in ms between pings.

Example:

const { sendMessage } = useWebSocket('ws://localhost:3000', {
  heartbeat: {
    message: 'ping',
    returnMessage: 'pong',
    timeout: 60000,
    interval: 25000,
  },
});

The readyState property returns an integer representing the current state of the WebSocket connection.

ReadyState Enum Values:

• -1 (UNINSTANTIATED): The WebSocket has not been instantiated yet (e.g., url is null or connect param is false).
• 0 (CONNECTING): The connection is being established.
• 1 (OPEN): The connection is active.
• 2 (CLOSING): The connection is in the process of closing.
• 3 (CLOSED): The connection is closed.

In Single Page Applications (SPAs), if you open new windows via window.open, the global state of the library might persist in the main window even after the child window is closed, because React does not finish the component lifecycle on window close.

To prevent issues when re-initializing components with the same URL, you can manually reset the global state for a specific connection using resetGlobalState(url).

import React, { useEffect } from 'react';
import { resetGlobalState } from 'react-use-websocket';

// inside second window opened via window.open
export const ChildWindow = () => {
  useEffect(() => {
    window.addEventListener('unload', () => {
      resetGlobalState('wss://echo.websocket.org');
    });
  }, []);
};

If you are connecting to a SocketIO backend, use the useSocketIO hook. SocketIO uses a non-standard message format that is not directly JSON-parsable by standard WebSocket clients.

Key Differences:

• lastMessage is not a MessageEvent; it is an object with { type, payload }.
• The API is identical to useWebSocket.

import { useSocketIO } from 'react-use-websocket';

const { sendMessage, lastMessage, readyState } = useSocketIO(
  'http://localhost:3000/'
);