React WebSocket Hook

Common errors

• TypeError: useWebSocket is not a function

  cause Incorrect import statement (e.g., default import instead of named) or trying to use CommonJS `require` in an ESM context.
  fix Ensure you are using `import { useWebSocket } from 'react-use-websocket';` and your project is configured for ESM if applicable.

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause The `useWebSocket` hook is being called outside of a React function component or a custom hook.
  fix Ensure `useWebSocket` is only invoked directly within the body of a React function component or another custom hook.

• WebSocket connection failed: wss://demos.kaazing.com/echo

  cause The `demos.kaazing.com/echo` server is frequently offline or unreachable, causing connection attempts to fail.
  fix Change the `socketUrl` to a more reliable endpoint like `wss://echo.websocket.org` for testing, or use a trusted production WebSocket server.

Warnings

• breaking Version 4.0.0 and above of `react-use-websocket` now depends on React 18. If your project is still on React 17 or older, you must install version 3.0.0.
  Fix: Upgrade your project to React 18, or install `react-use-websocket@3.0.0` if you need to stay on an older React version (e.g., `npm install --save react-use-websocket@3.0.0`).
• breaking In version 2.0.0, the return value of the `useWebSocket` hook changed from an array to an object. Destructuring must be updated accordingly.
  Fix: Update your hook usage from `const [sendMessage, lastMessage, readyState] = useWebSocket(...)` to `const { sendMessage, lastMessage, readyState } = useWebSocket(...)`.
• gotcha The `wss://demos.kaazing.com/echo` endpoint, often used in examples, has been intermittently unavailable. Relying on it for production or critical testing is not advised as it will lead to connection failures.
  Fix: Use a reliable WebSocket echo server (e.g., `wss://echo.websocket.org`) or your own backend for testing and production environments.
• gotcha To explicitly close or unsubscribe a component from a WebSocket connection, passing `false` as the third parameter to `useWebSocket` is the recommended method since v2.0.0. While setting `socketUrl` to `null` still works, it's less explicit.
  Fix: Prefer `useWebSocket(socketUrl, options, false)` for explicit unsubscription or closing.

Install

• npm install react-use-websocket npm
• yarn add react-use-websocket yarn
• pnpm add react-use-websocket pnpm

Imports

• useWebSocket
  wrong:

  import useWebSocket from 'react-use-websocket';
  const useWebSocket = require('react-use-websocket');

  correct:

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

  useWebSocket is a named export, not a default export. CommonJS require is not supported in modern React/ESM projects.
• ReadyState
  wrong:

  import ReadyState from 'react-use-websocket';

  correct:

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

  ReadyState is an enum representing the WebSocket connection status, used for conditional rendering or logic.
• Options
  wrong:

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

  correct:

  import type { Options } from 'react-use-websocket';

  When importing types like Options, it's best practice to use 'import type' for clarity and to ensure they are stripped during compilation.

Quickstart

This quickstart demonstrates setting up a basic WebSocket connection using `useWebSocket`, sending messages, and displaying incoming messages and the connection status in a React component.

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

export const WebSocketDemo = () => {
  // Public API that will echo messages sent to it back to the client
  const [socketUrl, setSocketUrl] = useState('wss://echo.websocket.org');
  const [messageHistory, setMessageHistory] = useState([]);

  const { sendMessage, lastMessage, readyState } = useWebSocket(socketUrl);

  useEffect(() => {
    if (lastMessage !== null) {
      setMessageHistory((prev) => prev.concat(lastMessage.data));
    }
  }, [lastMessage]);

  const handleClickChangeSocketUrl = useCallback(
    () => setSocketUrl('wss://demos.kaazing.com/echo'),
    []
  );

  const handleClickSendMessage = useCallback(() => sendMessage('Hello'), []);

  const connectionStatus = {
    [ReadyState.CONNECTING]: 'Connecting',
    [ReadyState.OPEN]: 'Open',
    [ReadyState.CLOSING]: 'Closing',
    [ReadyState.CLOSED]: 'Closed',
    [ReadyState.UNINSTANTIATED]: 'Uninstantiated',
  }[readyState];

  return (
    <div>
      <button onClick={handleClickChangeSocketUrl}>
        Click Me to change Socket Url
      </button>
      <button
        onClick={handleClickSendMessage}
        disabled={readyState !== ReadyState.OPEN}
      >
        Click Me to send 'Hello'
      </button>
      <span>The WebSocket is currently {connectionStatus}</span>
      {lastMessage ? <span>Last message: {lastMessage.data}</span> : null}
      <h3>Message History:</h3>
      <ul>
        {messageHistory.map((message, idx) => (
          <li key={idx}>{message}</li>
        ))}
      </ul>
    </div>
  );
};