Setting the file. One moment.
Subchapter 18.246
references/useWebSocket.mdMarkdown8 KBView on GitHub
Reactive WebSocket client.
import { useWebSocket } from '@vueuse/core'
const { status, data, send, open, close, ws } = useWebSocket('ws://websocketurl')| Property | Type | Description |
|---|---|---|
data | Ref<any> | Latest received data |
status | Ref<'OPEN' | 'CONNECTING' | 'CLOSED'> | Connection status |
ws | Ref<WebSocket> | WebSocket instance |
send | (data, useBuffer?) => boolean | Send data (buffers if not connected) |
open | () => void | Open/reconnect the connection |
close | (code?, reason?) => void | Close the connection |
const { data } = useWebSocket('ws://websocketurl', {
onConnected(ws) {
console.log('Connected!')
},
onDisconnected(ws, event) {
console.log('Disconnected!', event.code)
},
onError(ws, event) {
console.error('Error:', event)
},
onMessage(ws, event) {
console.log('Message:', event.data)
},
})See the Type Declarations for more options.
Enable by default.
Establish the connection immediately when the composable is called.
Enable by default.
If a URL is provided as a ref, when the URL changes, it will automatically reconnect to the new URL.
Enable by default.
This will call close() automatically when the beforeunload event is triggered or the associated effect scope is stopped.
Reconnect on errors automatically (disabled by default).
import { useWebSocket } from '@vueuse/core'
// ---cut---
const { status, data, close } = useWebSocket('ws://websocketurl', {
autoReconnect: true,
})Or with more controls over its behavior:
import { useWebSocket } from '@vueuse/core'
// ---cut---
const { status, data, close } = useWebSocket('ws://websocketurl', {
autoReconnect: {
retries: 3,
delay: 1000,
onFailed() {
alert('Failed to connect WebSocket after 3 retries')
},
},
})You can also pass a function to delay to calculate the delay based on the number of retries. This is useful for implementing exponential backoff:
import { useWebSocket } from '@vueuse/core'
// ---cut---
const { status, data, close } = useWebSocket('ws://websocketurl', {
autoReconnect: {
retries: 5,
// Exponential backoff: 1s, 2s, 4s, 8s, 16s
delay: retries => Math.min(1000 * 2 ** (retries - 1), 30000),
},
})import { useWebSocket } from '@vueuse/core'
// ---cut---
const { status, data, close } = useWebSocket('ws://websocketurl', {
autoReconnect: {
retries: 5,
// Linear backoff: 1s, 2s, 3s, 4s, 5s
delay: retries => retries * 1000,
},
})Explicitly calling close() won’t trigger the auto reconnection.
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:
import { useWebSocket } from '@vueuse/core'
// ---cut---
const { status, data, close } = useWebSocket('ws://websocketurl', {
heartbeat: true,
})Or with more controls:
import { useWebSocket } from '@vueuse/core'
// ---cut---
const { status, data, close } = useWebSocket('ws://websocketurl', {
heartbeat: {
message: 'ping',
scheduler: cb => useIntervalFn(cb, 2000),
pongTimeout: 1000,
},
})List of one or more subprotocols to use, in this case SOAP and WAMP.
import { useWebSocket } from '@vueuse/core'
// ---cut---
const { status, data, send, open, close } = useWebSocket('ws://websocketurl', {
protocols: ['soap'], // ['soap', 'wamp']
})export type WebSocketStatus = "OPEN" | "CONNECTING" | "CLOSED"
export type WebSocketHeartbeatMessage = string | ArrayBuffer | Blob
export interface UseWebSocketOptions {
onConnected?: (ws: WebSocket) => void
onDisconnected?: (ws: WebSocket, event: CloseEvent