useWebSocket | VueUse

useWebSocket
​
Category
Network
Export Size
1.34 kB
Last Changed
3 weeks ago

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']
})
Source
​

Source • Docs

Contributors
​
Anthony Fu
Ivan Demidov
Shinigami
Dan Rose
Antério Vieira
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.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)