EventSource

The EventSource interface is web content's interface to server-sent events. An EventSource instance opens a persistent connection to an HTTP server, which sends events in text/event-stream format. The connection remains open until closed by calling EventSource.close() (en-US).

Once the connection is opened, incoming messages from the server are delivered to your code in the form of message events.

Unlike WebSockets, server-sent events are unidirectional; that is, data messages are delivered in one direction, from the server to the client (such as a user's web browser). That makes them an excellent choice when there's no need to send data from the client to the server in message form. For example, EventSource is a useful approach for handling things like social media status updates, news feeds, or delivering data into a client-side storage mechanism like IndexedDB or web storage.

EventSource() (en-US)

Creates a new EventSource to handle receiving server-sent events from a specified URL, optionally in credentials mode.

This interface also inherits properties from its parent, EventTarget (en-US).

EventSource.readyState (en-US) Read only

A number representing the state of the connection. Possible values are CONNECTING (0), OPEN (1), or CLOSED (2).

EventSource.url Read only

A DOMString (en-US) representing the URL of the source.

EventSource.withCredentials (en-US) Read only

A Boolean (en-US) indicating whether the EventSource object was instantiated with cross-origin (CORS) credentials set (true), or not (false, the default).

EventSource.onerror (en-US)

Is an EventHandler (en-US) called when an error occurs and the error (en-US) event is dispatched on an EventSource object.

EventSource.onmessage (en-US)

Is an EventHandler (en-US) called when a message (en-US) event is received, that is when a message is coming from the source.

EventSource.onopen (en-US)

Is an EventHandler (en-US) called when an open (en-US) event is received, that is when the connection was just opened.

This interface also inherits methods from its parent, EventTarget (en-US).

EventSource.close() (en-US)

Closes the connection, if any, and sets the readyState attribute to CLOSED. If the connection is already closed, the method does nothing.

error (en-US)

Fired when a connection to an event source failed to open.

message (en-US)

Fired when data is received from an event source.

open (en-US)

Fired when a connection to an event source has opened.

In this basic example, an EventSource is created to receive events from the server; a page with the name sse.php is responsible for generating the events.

var evtSource = new EventSource('sse.php');
var eventList = document.querySelector('ul');

evtSource.onmessage = function(e) {
  var newElement = document.createElement("li");

  newElement.textContent = "message: " + e.data;
  eventList.appendChild(newElement);
}

Each received event causes our EventSource object's onmessage event handler to be run. It, in turn, creates a new <li> (en-US) element and writes the message's data into it, then appends the new element to the list element already in the document.

• Server-sent events
• Using server-sent events