Skip to content

useWebSocket ​

Category
Export Size
1.34 kB
Last Changed
last month

Reactive WebSocket client.

Usage ​

js
import { useWebSocket } from '@vueuse/core'

const { status, data, send, open, close } = useWebSocket('ws://websocketurl')

See the Type Declarations for more options.

Immediate ​

Auto-connect (enabled by default).

This will call open() automatically for you and you don't need to call it by yourself.

If url is provided as a ref, this also controls whether a connection is re-established when its value is changed (or whether you need to call open() again for the change to take effect).

Auto-close ​

Auto-close-connection (enabled by default).

This will call close() automatically when the beforeunload event is triggered or the associated effect scope is stopped.

Auto-reconnection ​

Reconnect on errors automatically (disabled by default).

js
const { status, data, close } = useWebSocket('ws://websocketurl', {
  autoReconnect: true,
})

Or with more controls over its behavior:

js
const { status, data, close } = useWebSocket('ws://websocketurl', {
  autoReconnect: {
    retries: 3,
    delay: 1000,
    onFailed() {
      alert('Failed to connect WebSocket after 3 retries')
    },
  },
})

Explicitly calling close() won't trigger the auto reconnection.

Heartbeat ​

It's common practice to send a small message (heartbeat) for every given time passed to keep the connection active. In this function we provide a convenient helper to do it:

js
const { status, data, close } = useWebSocket('ws://websocketurl', {
  heartbeat: true,
})

Or with more controls:

js
const { status, data, close } = useWebSocket('ws://websocketurl', {
  heartbeat: {
    message: 'ping',
    interval: 1000,
    pongTimeout: 1000,
  },
})

Sub-protocols ​

List of one or more subprotocols to use, in this case soap and wamp.

js
import { useWebSocket } from '@vueuse/core'

const { status, data, send, open, close } = useWebSocket('ws://websocketurl', {
  protocols: ['soap'], // ['soap', 'wamp']
})

Type Declarations ​

Show Type Declarations
typescript
export type WebSocketStatus = "OPEN" | "CONNECTING" | "CLOSED"
export interface UseWebSocketOptions {
  onConnected?: (ws: WebSocket) => void
  onDisconnected?: (ws: WebSocket, event: CloseEvent) => void
  onError?: (ws: WebSocket, event: Event) => void
  onMessage?: (ws: WebSocket, event: MessageEvent) => void
  /**
   * Send heartbeat for every x milliseconds passed
   *
   * @default false
   */
  heartbeat?:
    | boolean
    | {
        /**
         * Message for the heartbeat
         *
         * @default 'ping'
         */
        message?: string | ArrayBuffer | Blob
        /**
         * Interval, in milliseconds
         *
         * @default 1000
         */
        interval?: number
        /**
         * Heartbeat response timeout, in milliseconds
         *
         * @default 1000
         */
        pongTimeout?: number
      }
  /**
   * Enabled auto reconnect
   *
   * @default false
   */
  autoReconnect?:
    | boolean
    | {
        /**
         * Maximum retry times.
         *
         * Or you can pass a predicate function (which returns true if you want to retry).
         *
         * @default -1
         */
        retries?: number | (() => boolean)
        /**
         * Delay for reconnect, in milliseconds
         *
         * @default 1000
         */
        delay?: number
        /**
         * On maximum retry times reached.
         */
        onFailed?: Fn
      }
  /**
   * Automatically open a connection
   *
   * @default true
   */
  immediate?: boolean
  /**
   * Automatically close a connection
   *
   * @default true
   */
  autoClose?: boolean
  /**
   * List of one or more sub-protocol strings
   *
   * @default []
   */
  protocols?: string[]
}
export interface UseWebSocketReturn<T> {
  /**
   * Reference to the latest data received via the websocket,
   * can be watched to respond to incoming messages
   */
  data: Ref<T | null>
  /**
   * The current websocket status, can be only one of:
   * 'OPEN', 'CONNECTING', 'CLOSED'
   */
  status: Ref<WebSocketStatus>
  /**
   * Closes the websocket connection gracefully.
   */
  close: WebSocket["close"]
  /**
   * Reopen the websocket connection.
   * If there the current one is active, will close it before opening a new one.
   */
  open: Fn
  /**
   * Sends data through the websocket connection.
   *
   * @param data
   * @param useBuffer when the socket is not yet open, store the data into the buffer and sent them one connected. Default to true.
   */
  send: (data: string | ArrayBuffer | Blob, useBuffer?: boolean) => boolean
  /**
   * Reference to the WebSocket instance.
   */
  ws: Ref<WebSocket | undefined>
}
/**
 * Reactive WebSocket client.
 *
 * @see https://vueuse.org/useWebSocket
 * @param url
 */
export declare function useWebSocket<Data = any>(
  url: MaybeRefOrGetter<string | URL | undefined>,
  options?: UseWebSocketOptions,
): UseWebSocketReturn<Data>

Source ​

Source • Docs

Contributors ​

Anthony Fu
Ivan Demidov
Shinigami
Dan Rose
Antério Vieira
HengJing Wang
Evan
Vanweiping
alipay404
shanyi-front
丶远方
Fernando Fernández
Johann Kellerman
Dan Rose
cn.shperry
azaleta
Mikhailov Nikita
Jelf
Ernest
Roland Doda
Shangbu Li
webfansplz
Jan-Henrik Damaschke
Joacim de la Motte
Alex Kozack
iGalaxyz

Changelog ​

v10.8.0 on 2/20/2024
93b96 - fix: immediate should only be applied once, close #3676
9a47a - fix: reset wsRef on close, fix #3706 (#3707)
v10.6.0 on 11/9/2023
9b014 - fix: webworker support (#3469)
v10.5.0 on 10/7/2023
c3a69 - fix: ssr support (#3370)
v10.4.0 on 8/25/2023
aea27 - fix(useWebsocket): reset pongTimeout on close (#3324)
93372 - fix(useWebsocket): pongTimeout auto-reconnect no work (#3321)
v10.0.0-beta.4 on 4/13/2023
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
10e98 - feat(toRef)!: rename resolveRef to toRef
v9.12.0 on 1/29/2023
13924 - feat: allow undefined ref for url (#2473)
v9.5.0 on 11/9/2022
65f43 - fix: don't hide pong setTimeout reference (#2206)
86013 - feat(useWebsocket): url to be ref/computed (#2367)
v9.4.0 on 10/25/2022
d4c32 - fix: don't reconnect WebSocket if close issued between retries (#2330)
v9.2.0 on 9/5/2022
4c1f7 - feat: enhence heartbeat (#2170)
v9.0.0-beta.1 on 7/20/2022
a5d76 - fix: set initial status as CLOSED (#1960)
v8.9.3 on 7/14/2022
b461f - fix!: rename type WebSocketOptions to UseWebSocketOptions and WebSocketResult to UseWebSocketReturn (#1895)

Released under the MIT License.