react-websocket

react-websocket The real-time toolkit for React

One hook to connect, with shared sockets, automatic reconnects and typed messages built in. Add topics, state, requests, presence, games or AI agents on the same connection, and ship only what you import. Zero dependencies.

Get startedWhy react-websocket?API reference

Start in a minute

npm
pnpm
yarn
bun
npm install react-websocket
import { useWebSocket } from 'react-websocket';

export function Echo() {
  const { status, lastMessage, send } = useWebSocket('wss://echo.websocket.org');

  return (
    <div>
      <p>Status: {status}</p>
      <p>Last message: {String(lastMessage ?? '—')}</p>
      <button onClick={() => send('hello')}>Send</button>
    </div>
  );
}

No provider, no setup and no useEffect. That component already:

  • Shares one socket with every component that uses the same URL, through StrictMode, <Activity> and route changes.
  • Reconnects with exponential backoff and jitter, and at once when the network or the tab comes back.
  • Queues messages sent before the socket opens, and delivers them in order once it does.
  • Never connects during a server render, and hydrates without mismatches.

Add types when you're ready

Most servers send JSON. Turn on json and name what you receive and what you send:

import { useWebSocket } from 'react-websocket';

type Price = { symbol: string; price: number };

function Ticker() {
  const { status, lastMessage, send } = useWebSocket<Price, { subscribe: string }>(
    'wss://api.example.com/prices',
    {
      json: true,
      // Runs after every (re)connect, by which time `send` is assigned.
      onOpen: () => send({ subscribe: 'ACME' })
    }
  );

  if (status !== 'open') return <p>{status}…</p>;
  return <p>ACME: {lastMessage?.price ?? '—'}</p>;
}

To check messages at runtime too, pass a schema from zod, valibot or arktype, and the types are inferred from it. The getting started guide goes on from here.

The toolkit

Everything builds on the client that useWebSocket uses. Each piece is a separate import, so a page that only connects ships only the core, about 4 kB, and most pieces add under 2 kB. None of them imposes a wire protocol: you describe your server's messages, and they do the bookkeeping.

Connect

Where every app starts: connections shared by URL, automatic reconnects, a send queue, typed and validated messages, Suspense and server rendering.

useWebSocket · createWebSocket · useWebSocketStatus · useWebSocketEvent

Getting started · Shared clients · Reconnecting · Messages and types · Suspense · Server rendering · Without React

Live data

Subscriptions that are sent again after every reconnect, numbered feeds that arrive once and in order, and stores reduced from messages that re-render only the slice that changed.

createWebSocketTopics · createWebSocketFeeds · createWebSocketState · useWebSocketTopic · useWebSocketState · useInView

Topics · State

Requests and streams

Await a reply, stream replies such as an LLM's tokens with a Stop button that tells the server, and measure the round-trip time and the server's clock.

createWebSocketRequests · useWebSocketStream · createWebSocketLatency · useWebSocketLatency

Requests · Streams · Latency

AI agents

Answer an agent's tool calls in the browser or from an approval dialog, keep a streamed answer through a reload, run AG-UI agents, and handle voice interruptions.

createWebSocketResponder · useAgentApproval · createWebSocketRuns · useAgentRun · useAgUiAgent · react-websocket/ag-ui

AI agents · AG-UI · Voice

Multiplayer and presence

Live cursors that expire when a peer vanishes, a send rate that adapts to the connection, and snapshot interpolation with client-side prediction for games.

createWebSocketPresence · useWebSocketPresence · createWebSocketSendRate · react-websocket/timeline

Presence · Games

Transports and offline

One connection shared by every tab, WebTransport with datagrams and a WebSocket fallback, and an IndexedDB outbox that keeps messages until the server acknowledges them.

react-websocket/tabs · react-websocket/webtransport · react-websocket/outbox · useWebSocketOutbox

Tabs · WebTransport · Outbox

Debug and test

A devtools panel, faults injected in development, and sessions recorded to a file and replayed without a server.

react-websocket/devtools · react-websocket/chaos · react-websocket/replay

Testing · Devtools · Chaos · Replay

Works with your stack

react-websocket uses the standard WebSocket API, so any WebSocket server works: Node's ws, Hono, Django Channels, Tornado, Go, Phoenix or Cloudflare Durable Objects. In the browser it runs in a Vite app or in a server-rendered framework such as Next.js, React Router or Astro, and react-websocket/core brings the same client to code without React.

The repository has runnable examples for Next.js, Astro, Remix, Hono and Tornado, and a multiplayer game. The real-world guides build whole apps, client and server: an AI chatbot, a voice assistant, a party game, a team chat, a trading dashboard and more.