Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
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.

JS The text/event-stream format

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS A stand-in EventSource with named events

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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(). The onmessage handler only receives events without an event: field.
  • Automatic reconnection. After a network drop, the browser reconnects and sends a Last-Event-ID request header. Your server should use it to resume. Call close() to stop reconnecting for good.
  • error does not always mean failure. It fires during reconnect attempts too; check readyState (CONNECTING means it will retry, CLOSED means 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.data is text from the server. Insert it with textContent, not innerHTML.

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.