use-websocket

Open a WebSocket with raw payloads.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useWebSocket } from "@vizejs/composable/use-websocket";

Try it

Connect a chat to a WebSocket

Open a WebSocket on demand, send messages and react to the connection state.

Open the interactive example

What to observe: Connect opens the socket; Say hello sends a message and shows the echo. Say hello is enabled only while the socket is open.

The docs have no server, so host supplies an echo socket; drop it in your app. Use heartbeat to detect dead connections and bufferWhileConnecting to queue early messages.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useWebSocket } from "@vizejs/composable/use-websocket";

// The docs have no server, so this class echoes messages back. In your app, drop `host`
// and use your WebSocket server's URL.
class EchoServer extends EventTarget {
  constructor(_url: string) {
    super();
    queueMicrotask(() => this.dispatchEvent(new Event("open")));
  }

  send(data: unknown) {
    queueMicrotask(() =>
      this.dispatchEvent(new MessageEvent("message", { data: `Echo: ${String(data)}` })),
    );
  }

  close() {
    queueMicrotask(() => this.dispatchEvent(new CloseEvent("close", { code: 1000 })));
  }
}

const { status, data, open, close, send } = useWebSocket("wss://chat.example.com", {
  host: EchoServer,
  immediate: false,
  autoReconnect: false,
});
</script>

<template>
  <div class="composable-example">
    <p>Connect a chat to a WebSocket server and react to its connection state.</p>
    <div class="example-actions">
      <button type="button" :disabled="status !== 'closed'" @click="() => open()">Connect</button>
      <button type="button" :disabled="status !== 'open'" @click="() => send('Hello!')">
        Say hello
      </button>
      <button type="button" :disabled="status === 'closed'" @click="() => close()">
        Disconnect
      </button>
    </div>
    <output aria-live="polite">Status: {{ status }}{{ data ? ` · ${data}` : "" }}</output>
  </div>
</template>

Runtime contract

API

useWebSocket

Open a WebSocket with raw payloads.

function useWebSocket( url: MaybeRefOrGetter<string | URL | null | undefined>, options?: UseWebSocketOptions<WebSocketRawData, WebSocketSendData>, ): WebSocketControls<WebSocketRawData, WebSocketSendData>

useWebSocket

Open a WebSocket with typed messages. parse is required unless raw payloads fit Incoming; serialize is required unless Outgoing is already sendable.

function useWebSocket<Incoming = WebSocketRawData, Outgoing = WebSocketSendData>( url: MaybeRefOrGetter<string | URL | null | undefined>, options: UseWebSocketOptions<Incoming, Outgoing> & WebSocketCodecRequirements<Incoming, Outgoing>, ): WebSocketControls<Incoming, Outgoing>

useWebSocket

Reactive WebSocket with typed messages, auto-reconnect, and heartbeat. Unexpected closes reconnect with exponential backoff when autoReconnect is enabled; close() is always final until open() is called again. Messages sent while connecting are queued. The connection and all timers are released when the owning reactive scope stops; outside a scope the caller owns close(). Server rendering never connects: automatic connection requires a browser or an explicit host, and status stays "closed".

function useWebSocket( url: MaybeRefOrGetter<string | URL | null | undefined>, options: UseWebSocketOptions<unknown, unknown> = {}, ): WebSocketControls<unknown, unknown>

const chat = useWebSocket<ChatEvent, ChatCommand>("wss://example.test/chat", {
  parse: (raw) => parseChatEvent(String(raw)),
  serialize: (command) => JSON.stringify(command),
  autoReconnect: { retries: 5 },
  heartbeat: true,
});
chat.send({ type: "join", room: "general" });

Types

WebSocketLike

Minimal WebSocket instance used by useWebSocket.

WebSocketReconnectOptions

Options for automatic reconnection.

WebSocketHeartbeatOptions

Options for the keep-alive heartbeat.

UseWebSocketOptions

Options for useWebSocket. Callbacks that consume message types use method syntax so options typed for concrete messages remain assignable to the implementation signature.

WebSocketControls

Reactive state and controls returned by useWebSocket.