useWebSocket

Open a WebSocket from a component, with automatic reconnects, an optional send queue and every message delivered in order.

import { useState } from 'react';
import { useWebSocket } from '@gio.js/react';

export function Chat({ room }: { room: string }) {
  const [messages, setMessages] = useState<string[]>([]);
  const { send, readyState } = useWebSocket(`/api/chat/${room}`, {
    onMessage: (data) => setMessages((list) => [...list, String(data)]),
  });
  return (
    <>
      <p>{readyState === 1 ? 'Live' : 'Connecting...'}</p>
      <ul>{messages.map((m, i) => <li key={i}>{m}</li>)}</ul>
      <button onClick={() => send('hello')}>Say hello</button>
    </>
  );
}

The server side is a wsHandler export in the route.ts for that path, here app/api/chat/[room]/route.ts. The socket needs its own URL: a folder cannot hold both a page.tsx and a route.ts. See wsHandler and WebSockets.

Reference

Parameters

Options

The options are read when they are needed, so passing a new object or new callbacks on every render never reconnects.

ReconnectOptions

Returns

The types are exported as UseWebSocketOptions, ReconnectOptions, UseWebSocketResult and WebSocketData.

Reconnecting

After an unintended close the hook waits and connects again. Retry n (from 0) waits between half and all of min(maxDelayMs, initialDelayMs × 2^n) - with the defaults about 0.25-0.5 s, then 0.5-1 s, 1-2 s and so on up to 15-30 s - so clients do not all return in the same instant after a server restart.

It never reconnects after close(), after unmount, or once maxAttempts is reached. The backoff starts over only when a connection stayed open for minUptimeMs: a server that accepts the upgrade and closes straight away (1013, 1011) keeps being backed off from.

Examples

Sending JSON

import { useWebSocket } from '@gio.js/react';

interface Cursor {
  x: number;
  y: number;
}

export function CursorSync({ onRemote }: { onRemote: (cursor: Cursor) => void }) {
  const { send } = useWebSocket('/board/live', {
    onMessage: (data) => {
      if (typeof data === 'string') onRemote(JSON.parse(data) as Cursor);
    },
  });
  return (
    <div
      className="board"
      onPointerMove={(e) => send(JSON.stringify({ x: e.clientX, y: e.clientY }))}
    />
  );
}

A connection indicator

const { readyState, isReconnecting, reconnectAttempts, reconnect } = useWebSocket('/feed', {
  reconnect: { maxAttempts: 10 },
});

if (isReconnecting) return <p>Reconnecting (attempt {reconnectAttempts})...</p>;
if (readyState === 3) return <button onClick={reconnect}>Reconnect</button>; // closed

Queueing while offline

const { send } = useWebSocket('/notes/42', { queueWhileDisconnected: { maxMessages: 500 } });

// Sent at once when open; otherwise kept and sent on the next open.
const accepted = send(JSON.stringify({ op: 'insert', text: 'hi' }));
if (!accepted) showWarning('Change not sent');

A custom reconnect policy

useWebSocket('/prices', {
  // Also give up when the server says the market is closed (4503 would otherwise retry).
  shouldReconnect: (event) => event.code !== 1000 && event.code !== 4503 && !(event.code >= 4000 && event.code < 4500),
});

Good to know

• The hook does nothing during server rendering (readyState is -1, send returns false); the socket opens after the component mounts in the browser. In the server-only root layout it never runs.
• A message is only ever sent to the URL it was queued for: when url changes (another room), whatever is still queued is dropped.
• Binary frames always arrive as ArrayBuffer (binaryType is fixed), never as Blob.
• Cookies go with the upgrade request, and the server refuses cross-site upgrades by checking Origin ([security.websocket]).
• A worker restart closes every socket with 1001, and the hook reconnects; room memberships are re-established by your wsHandler when it accepts the new connection.
• readyState never reports 2 (closing): it moves from 1 to 3 when the close completes.

Related

• WebSockets - the guide: handlers, auth, rooms, close codes.
• wsHandler - the server side.
• broadcast - send to a room from any route handler.
• [websocket] - max_connections, ping_interval_secs.

Version history