JavaScript Reference ยท Browser and Web APIs
The EventSource object
Reference for EventSource and server-sent events: connecting, message and named events, the text/event-stream format, automatic reconnection and close().
EventSource opens a long-lived HTTP connection over which the server pushes events to the browser. This is called Server-Sent Events (SSE). It is one-way, from server to client, and it is plain HTTP: the response has the content type text/event-stream and simply never ends.
Compared with a WebSocket, EventSource is simpler. The browser reconnects automatically after a dropped connection and tells the server the ID of the last event it saw, so the server can resume where it stopped. It cannot send messages back (use fetch() for that), and it carries text only.
const source = new EventSource("/events"); source.onmessage = (event) => console.log(event.data);
Try it
There is no server in the sandboxed editors, so these examples show the wire format and the parsing rules directly, which is the part you need to understand when writing a server.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
const source = new EventSource(url, options) source.addEventListener(type, handler) source.close()
| Name | Description |
|---|---|
url |
The endpoint that returns text/event-stream. |
options.withCredentials |
If true, cookies are sent on a cross-origin request. Default false. |
Properties: readyState (0 connecting, 1 open, 2 closed), url, withCredentials. Constants EventSource.CONNECTING, OPEN and CLOSED hold those numbers.
Events: open, error, message (events without an event: field) and any custom name the server sets with event:. For message events, event.data is the text and event.lastEventId is the last id: seen.
Server fields: data: (can repeat, joined with newlines), event: (type name), id: (sets the last event ID), retry: (reconnect delay in milliseconds) and lines starting with : (comments, ignored).
Usage notes
- Custom event names need
addEventListener(). Theonmessagehandler only receives events without anevent:field. - Automatic reconnection. After a network drop, the browser reconnects and sends a
Last-Event-IDrequest header. Your server should use it to resume. Callclose()to stop reconnecting for good. errordoes not always mean failure. It fires during reconnect attempts too; checkreadyState(CONNECTINGmeans it will retry,CLOSEDmeans it gave up).- GET only, no custom headers. If you need to send a body or an authorization header, use
fetch()with a streaming response reader instead. - Connection limits. On HTTP/1.1, browsers allow only about six connections per host, shared across tabs; HTTP/2 raises that limit.
- Proxies and buffering. Servers and proxies must not buffer the response, and should send a comment line now and then as a keep-alive.
- Always escape.
event.datais text from the server. Insert it withtextContent, notinnerHTML.
Browser support
EventSource is supported in all current browsers. It is not available inside some worker or non-browser environments, so feature-detect when you need it there.