1---
2category: Network
3---
4 
5# useEventSource
6 
7An [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) or [Server-Sent-Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) instance opens a persistent connection to an HTTP server, which sends events in text/event-stream format.
8 
9## Usage
10 
11```ts
12import { useEventSource } from '@vueuse/core'
13 
14const { status, data, error, close } = useEventSource('https://event-source-url')
15```
16 
17See the [Type Declarations](#type-declarations) for more options.
18 
19### Named Events
20 
21You can define named events with the second parameter
22 
23```ts
24import { useEventSource } from '@vueuse/core'
25// ---cut---
26const { event, data } = useEventSource(
27  'https://event-source-url',
28  ['notice', 'update']
29)
30```
31 
32### immediate
33 
34Enable by default.
35 
36Establish the connection immediately when the composable is called.
37 
38### autoConnect
39 
40Enable by default.
41 
42If url is provided as a ref, when the url changes, it will automatically reconnect to the new url.
43 
44### Auto Reconnection on Errors
45 
46Reconnect on errors automatically (disabled by default).
47 
48```ts
49import { useEventSource } from '@vueuse/core'
50// ---cut---
51const { status, data, close } = useEventSource(
52  'https://event-source-url',
53  [],
54  {
55    autoReconnect: true,
56  }
57)
58```
59 
60Or with more controls over its behavior:
61 
62```ts
63import { useEventSource } from '@vueuse/core'
64// ---cut---
65const { status, data, close } = useEventSource(
66  'https://event-source-url',
67  [],
68  {
69    autoReconnect: {
70      retries: 3,
71      delay: 1000,
72      onFailed() {
73        alert('Failed to connect EventSource after 3 retries')
74      },
75    },
76  }
77)
78```
79 
80### Data Serialization
81 
82Apply custom transformations to incoming data using a serialization function.
83 
84```ts
85import { useEventSource } from '@vueuse/core'
86// ---cut---
87const { data } = useEventSource(
88  'https://event-source-url',
89  [],
90  {
91    serializer: {
92      read: rawData => JSON.parse(rawData),
93    },
94  }
95)
96 
97// If server sends: '{"name":"John","age":30}'
98// data.value will be: { name: 'John', age: 30 }
99```
100 
101## Type Declarations
102 
103```ts
104export type EventSourceStatus = "CONNECTING" | "OPEN" | "CLOSED"
105export interface UseEventSourceOptions<Data> extends EventSourceInit {
106  /**
107   * Enabled auto reconnect
108   *
109   * @default false
110   */
111  autoReconnect?:
112    | boolean
113    | {
114        /**
115         * Maximum retry times.
116         *
117         * Or you can pass a predicate function (which returns true if you want to retry).
118         *
119         * @default -1
120         */
121        retries?: number | (() => boolean)
122        /**
123         * Delay for reconnect, in milliseconds
124         *
125         * @default 1000
126         */
127        delay?: number
128        /**
129         * On maximum retry times reached.
130         */
131        onFailed?: Fn
132      }
133  /**
134   * Immediately open the connection when calling this composable
135   *
136   * @default true
137   */
138  immediate?: boolean
139  /**
140   * Automatically connect to the websocket when URL changes
141   *
142   * @default true
143   */
144  autoConnect?: boolean
145  /**
146   * Custom data serialization
147   */
148  serializer?: {
149    read: (v?: string) => Data
150  }
151}
152export interface UseEventSourceReturn<Events extends string[], Data = any> {
153  /**
154   * Reference to the latest data received via the EventSource,
155   * can be watched to respond to incoming messages
156   */
157  data: ShallowRef<Data | null>
158  /**
159   * The current state of the connection, can be only one of:
160   * 'CONNECTING', 'OPEN' 'CLOSED'
161   */
162  status: ShallowRef<EventSourceStatus>
163  /**
164   * The latest named event
165   */
166  event: ShallowRef<Events[number] | null>
167  /**
168   * The current error
169   */
170  error: ShallowRef<Event | null>
171  /**
172   * Closes the EventSource connection gracefully.
173   */
174  close: EventSource["close"]
175  /**
176   * Reopen the EventSource connection.
177   * If there the current one is active, will close it before opening a new one.
178   */
179  open: Fn
180  /**
181   * Reference to the current EventSource instance.
182   */
183  eventSource: Ref<EventSource | null>
184  /**
185   * The last event ID string, for server-sent events.
186   * @see https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/lastEventId
187   */
188  lastEventId: ShallowRef<string | null>
189}
190/**
191 * Reactive wrapper for EventSource.
192 *
193 * @see https://vueuse.org/useEventSource
194 * @see https://developer.mozilla.org/en-US/docs/Web/API/EventSource/EventSource EventSource
195 * @param url
196 * @param events
197 * @param options
198 */
199export declare function useEventSource<Events extends string[], Data = any>(
200  url: MaybeRefOrGetter<string | URL | undefined>,
201  events?: Events,
202  options?: UseEventSourceOptions<Data>,
203): UseEventSourceReturn<Events, Data>
204```
205