useWebSocket

Features

• Built-in Validation: Validate messages with zod, valibot, arktype or with a simple function.
• Connection Reuse: Share a WebSocket connection across multiple hook instances.
• Automatic Reconnect: Configurable reconnection strategies for resilient connections.
• Ping Support: Built-in ping to keep connections alive.
• Message Queueing: Outgoing messages are queued while connecting.
• Automatic Parsing/Serialization: Customizable message parsing and serialization.
• Friendly API: Simple, ergonomic API for sending messages and tracking connection state.

Installation

npm install @1hook/use-websocket

Quick Start

import { z } from 'zod'
import { defineWebSocket } from '@1hook/use-websocket'

export const useWebSocket = defineWebSocket({
  ping: { interval: 10000 },
  reconnect: { delay: 5000 },
})

const { send } = useWebSocket({
  url: 'wss://echo.websocket.org',
  validate: z.object({ text: z.string() }),
  onMessage: console.log,
})

send({ text: 'Hello!' })

Validation

The validate option ensures incoming messages match your expected format, providing both runtime validation and type safety.

👉 Functional validation

For simple cases you can use a function to validate the incoming message.

useWebSocket({
  url: 'wss://echo.websocket.org',
  validate: (message) => String(message),
  onMessage: (message) => {
    // message: string
  },
})

👉 Schema validation

For more complex cases you can use a schema to validate the cookie value. Compatible validation libraries include zod 3.24+, valibot 1.0+ or arktype 2.0+. Check out Standard Schema for more info.

useWebSocket({
  url: 'wss://echo.websocket.org',
  validate: z.object({ type: z.string(), text: z.string() }),
  onMessage: (message) => {
    // message: { type: string, text: string }
  },
})

Message Filtering

Sometimes you need to selectively process messages based on their content. Rather than writing complex validation logic to handle every possible message format, you can simply ignore unwanted messages.

Return null | undefined from the validate option to skip processing specific messages. The hook will silently ignore these messages and only trigger onMessage for validated ones.

useWebSocket({
  url: 'wss://echo.websocket.org',
  validate: z
    .object({ type: z.string(), text: z.string() })
    .nullable() // allows returning null from catch() to ignore invalid messages
    .catch(null),
  onMessage: (message) => {
    // message: { type: string, text: string }
  },
})

Note that returning null or undefined from the parseMessage option will also ignore messages.

Custom Parsing/Serialization

You can configure default message parsing and serialization in defineWebSocket, while still having the flexibility to override these settings in individual useWebSocket calls.

defineWebSocket({
  parseMessage(event) {
    if (typeof event.data !== 'string') return event.data
    return JSON.parse(event.data)
  },
  serializeMessage(msg) {
    return JSON.stringify(msg)
  },
})

Since JSON parsing and serialization are the default behavior, you typically won't need to customize these settings.

Typesafe message sending

Type the serializeMessage parameter to constrain what messages can be sent through the send method.

type OutgoingMessage = { type: string; text: string }

const { send } = useWebSocket({
  url: 'wss://echo.websocket.org',
  serializeMessage(message: OutgoingMessage) {
    return JSON.stringify(message)
  },
})

Now the send method only accepts messages matching the OutgoingMessage type.

// ✅ ok
send({ type: 'hello', text: 'world' })

// ❌ error
send({ type: 'hello', text: 123 })

Closing the connection

The WebSocket connection automatically closes when there are no more active listeners. The listeners are removed when

• the hook unmounts
• The url is set to null

Note that if the connection closes for any other reason (like network issues, server-side closure or using the close method of the WebSocket instance directly), the configured reconnection strategy will attempt to restore the connection.

useWebSocket({
  url: enabled ? 'wss://echo.websocket.org' : null,
})

API Reference

👉 defineWebSocket

function defineWebSocket(options: DefineWebSocketOptions): useWebSocket

👉 useWebSocket

Send and Receive messages from a WebSocket server.

function useWebSocket(options: UseWebSocketOptions): UseWebSocketReturn