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.
Constructor
EventSource()
(en-US)- Creates a new
EventSource
to handle receiving server-sent events from a specified URL, optionally in credentials mode.
Properties
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
), orCLOSED
(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 theEventSource
object was instantiated with cross-origin (CORS) credentials set (true
), or not (false
, the default).
Event handlers
EventSource.onerror
(en-US)- Is an
EventHandler
(en-US) called when an error occurs and theerror
(en-US) event is dispatched on anEventSource
object. EventSource.onmessage
(en-US)- Is an
EventHandler
(en-US) called when amessage
(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 anopen
(en-US) event is received, that is when the connection was just opened.
Methods
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 toCLOSED
. If the connection is already closed, the method does nothing.
Events
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.
Examples
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.
Note: You can find a full example on GitHub — see Simple SSE demo using PHP.
Specifications
Specification | Status |
---|---|
HTML Living Standard The definition of 'EventSource' in that specification. |
Living Standard |
Browser compatibility
BCD tables only load in the browser