1---
2category: Network
3---
4 
5# useWebSocket
6 
7Reactive [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket) client.
8 
9## Usage
10 
11```ts
12import { useWebSocket } from '@vueuse/core'
13 
14const { status, data, send, open, close, ws } = useWebSocket('ws://websocketurl')
15```
16 
17### Return Values
18 
19| Property | Type                                      | Description                          |
20| -------- | ----------------------------------------- | ------------------------------------ |
21| `data`   | `Ref<any>`                                | Latest received data                 |
22| `status` | `Ref<'OPEN' \| 'CONNECTING' \| 'CLOSED'>` | Connection status                    |
23| `ws`     | `Ref<WebSocket>`                          | WebSocket instance                   |
24| `send`   | `(data, useBuffer?) => boolean`           | Send data (buffers if not connected) |
25| `open`   | `() => void`                              | Open/reconnect the connection        |
26| `close`  | `(code?, reason?) => void`                | Close the connection                 |
27 
28### Callbacks
29 
30```ts
31const { data } = useWebSocket('ws://websocketurl', {
32  onConnected(ws) {
33    console.log('Connected!')
34  },
35  onDisconnected(ws, event) {
36    console.log('Disconnected!', event.code)
37  },
38  onError(ws, event) {
39    console.error('Error:', event)
40  },
41  onMessage(ws, event) {
42    console.log('Message:', event.data)
43  },
44})
45```
46 
47See the [Type Declarations](#type-declarations) for more options.
48 
49### immediate
50 
51Enable by default.
52 
53Establish the connection immediately when the composable is called.
54 
55### autoConnect
56 
57Enable by default.
58 
59If a URL is provided as a ref, when the URL changes, it will automatically reconnect to the new URL.
60 
61### autoClose
62 
63Enable by default.
64 
65This will call `close()` automatically when the `beforeunload` event is triggered or the associated effect scope is stopped.
66 
67### autoReconnect
68 
69Reconnect on errors automatically (disabled by default).
70 
71```ts
72import { useWebSocket } from '@vueuse/core'
73// ---cut---
74const { status, data, close } = useWebSocket('ws://websocketurl', {
75  autoReconnect: true,
76})
77```
78 
79Or with more controls over its behavior:
80 
81```ts
82import { useWebSocket } from '@vueuse/core'
83// ---cut---
84const { status, data, close } = useWebSocket('ws://websocketurl', {
85  autoReconnect: {
86    retries: 3,
87    delay: 1000,
88    onFailed() {
89      alert('Failed to connect WebSocket after 3 retries')
90    },
91  },
92})
93```
94 
95You can also pass a function to `delay` to calculate the delay based on the number of retries. This is useful for implementing exponential backoff:
96 
97```ts
98import { useWebSocket } from '@vueuse/core'
99// ---cut---
100const { status, data, close } = useWebSocket('ws://websocketurl', {
101  autoReconnect: {
102    retries: 5,
103    // Exponential backoff: 1s, 2s, 4s, 8s, 16s
104    delay: retries => Math.min(1000 * 2 ** (retries - 1), 30000),
105  },
106})
107```
108 
109```ts
110import { useWebSocket } from '@vueuse/core'
111// ---cut---
112const { status, data, close } = useWebSocket('ws://websocketurl', {
113  autoReconnect: {
114    retries: 5,
115    // Linear backoff: 1s, 2s, 3s, 4s, 5s
116    delay: retries => retries * 1000,
117  },
118})
119```
120 
121Explicitly calling `close()` won't trigger the auto reconnection.
122 
123### heartbeat
124 
125It'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:
126 
127```ts
128import { useWebSocket } from '@vueuse/core'
129// ---cut---
130const { status, data, close } = useWebSocket('ws://websocketurl', {
131  heartbeat: true,
132})
133```
134 
135Or with more controls:
136 
137```ts
138import { useWebSocket } from '@vueuse/core'
139// ---cut---
140const { status, data, close } = useWebSocket('ws://websocketurl', {
141  heartbeat: {
142    message: 'ping',
143    scheduler: cb => useIntervalFn(cb, 2000),
144    pongTimeout: 1000,
145  },
146})
147```
148 
149### Sub-protocols
150 
151List of one or more subprotocols to use, in this case SOAP and WAMP.
152 
153```ts
154import { useWebSocket } from '@vueuse/core'
155// ---cut---
156const { status, data, send, open, close } = useWebSocket('ws://websocketurl', {
157  protocols: ['soap'], // ['soap', 'wamp']
158})
159```
160 
161## Type Declarations
162 
163```ts
164export type WebSocketStatus = "OPEN" | "CONNECTING" | "CLOSED"
165export type WebSocketHeartbeatMessage = string | ArrayBuffer | Blob
166export interface UseWebSocketOptions {
167  onConnected?: (ws: WebSocket) => void
168  onDisconnected?: (ws: WebSocket, event: CloseEvent) => void
169  onError?: (ws: WebSocket, event: Event) => void
170  onMessage?: (ws: WebSocket, event: MessageEvent) => void
171  /**
172   * Send heartbeat for every x milliseconds passed
173   *
174   * @default false
175   */
176  heartbeat?:
177    | boolean
178    | (ConfigurableScheduler & {
179        /**
180         * Message for the heartbeat
181         *
182         * @default 'ping'
183         */
184        message?: MaybeRefOrGetter<WebSocketHeartbeatMessage>
185        /**
186         * Response message for the heartbeat, if undefined the message will be used
187         */
188        responseMessage?: MaybeRefOrGetter<WebSocketHeartbeatMessage>
189        /**
190         * Interval, in milliseconds
191         *
192         * @deprecated Please use `scheduler` option instead
193         * @default 1000
194         */
195        interval?: number
196        /**
197         * Heartbeat response timeout, in milliseconds
198         *
199         * @default 1000
200         */
201        pongTimeout?: number
202      })
203  /**
204   * Enabled auto reconnect
205   *
206   * @default false
207   */
208  autoReconnect?:
209    | boolean
210    | {
211        /**
212         * Maximum retry times.
213         *
214         * Or you can pass a predicate function (which returns true if you want to retry).
215         *
216         * @default -1
217         */
218        retries?: number | ((retried: number) => boolean)
219        /**
220         * Delay for reconnect, in milliseconds
221         *
222         * Or you can pass a function to calculate the delay based on the number of retries.
223         *
224         * @default 1000
225         */
226        delay?: number | ((retries: number) => number)
227        /**
228         * On maximum retry times reached.
229         */
230        onFailed?: Fn
231      }
232  /**
233   * Immediately open the connection when calling this composable
234   *
235   * @default true
236   */
237  immediate?: boolean
238  /**
239   * Automatically connect to the websocket when URL changes
240   *
241   * @default true
242   */
243  autoConnect?: boolean
244  /**
245   * Automatically close a connection
246   *
247   * @default true
248   */
249  autoClose?: boolean
250  /**
251   * List of one or more sub-protocol strings
252   *
253   * @default []
254   */
255  protocols?: string[]
256}
257export interface UseWebSocketReturn<T> {
258  /**
259   * Reference to the latest data received via the websocket,
260   * can be watched to respond to incoming messages
261   */
262  data: Ref<T | null>
263  /**
264   * The current websocket status, can be only one of:
265   * 'OPEN', 'CONNECTING', 'CLOSED'
266   */
267  status: ShallowRef<WebSocketStatus>
268  /**
269   * Closes the websocket connection gracefully.
270   */
271  close: WebSocket["close"]
272  /**
273   * Reopen the websocket connection.
274   * If there the current one is active, will close it before opening a new one.
275   */
276  open: Fn
277  /**
278   * Sends data through the websocket connection.
279   *
280   * @param data
281   * @param useBuffer when the socket is not yet open, store the data into the buffer and sent them one connected. Default to true.
282   */
283  send: (data: string | ArrayBuffer | Blob, useBuffer?: boolean) => boolean
284  /**
285   * Reference to the WebSocket instance.
286   */
287  ws: Ref<WebSocket | undefined>
288}
289/**
290 * Reactive WebSocket client.
291 *
292 * @see https://vueuse.org/useWebSocket
293 * @param url
294 */
295export declare function useWebSocket<Data = any>(
296  url: MaybeRefOrGetter<string | URL | undefined>,
297  options?: UseWebSocketOptions,
298): UseWebSocketReturn<Data>
299```
300