---
title: EventSource
slug: Web/API/EventSource
tags:
  - API
  - Communications
  - EventSource
  - Interface
  - NeedsTranslation
  - Reference
  - Server Sent Events
  - Server-sent events
  - TopicStub
  - messaging
translation_of: Web/API/EventSource
---
<div>{{APIRef("Server Sent Events")}}</div>

<p><span class="seoSummary">The <strong><code>EventSource</code></strong> interface is web content's interface to <a href="/en-US/docs/Web/API/Server-sent_events">server-sent events</a>. An <code>EventSource</code> instance opens a persistent connection to an <a href="/en-US/docs/Web/HTTP">HTTP</a> server, which sends <a href="/en-US/docs/Web/API/Document_Object_Model/Events">events</a> in <code>text/event-stream</code> format.</span> The connection remains open until closed by calling {{domxref("EventSource.close()")}}.</p>

<p>Once the connection is opened, incoming messages from the server are delivered to your code in the form of {{event("message")}} events.</p>

<p>Unlike <a href="/en-US/docs/Web/API/WebSockets_API">WebSockets</a>, 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, <code>EventSource</code> is a useful approach for handling things like social media status updates, news feeds, or delivering data into a <a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Client-side_storage">client-side storage</a> mechanism like <a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB</a> or <a href="/en-US/docs/Web/API/Web_Storage_API">web storage</a>.</p>

<h2 id="Constructor">Constructor</h2>

<dl>
 <dt>{{domxref("EventSource.EventSource", "EventSource()")}}</dt>
 <dd>Creates a new <code>EventSource</code> to handle receiving server-sent events from a specified URL, optionally in credentials mode.</dd>
</dl>

<h2 id="Properties">Properties</h2>

<p><em>This interface also inherits properties from its parent, {{domxref("EventTarget")}}.</em></p>

<dl>
 <dt>{{domxref("EventSource.readyState")}} {{readonlyinline}}</dt>
 <dd>A number representing the state of the connection. Possible values are <code>CONNECTING</code> (<code>0</code>), <code>OPEN</code> (<code>1</code>), or <code>CLOSED</code> (<code>2</code>).</dd>
 <dt>{{domxref("EventSource.url")}} {{readonlyinline}}</dt>
 <dd>A {{domxref("DOMString")}} representing the URL of the source.</dd>
 <dt>{{domxref("EventSource.withCredentials")}} {{readonlyinline}}</dt>
 <dd>A {{domxref("Boolean")}} indicating whether the <code>EventSource</code> object was instantiated with cross-origin (<a href="/en-US/docs/Web/HTTP/CORS">CORS</a>) credentials set (<code>true</code>), or not (<code>false</code>, the default).</dd>
</dl>

<h3 id="Event_handlers">Event handlers</h3>

<dl>
 <dt>{{domxref("EventSource.onerror")}}</dt>
 <dd>Is an {{domxref("EventHandler")}} called when an error occurs and the {{domxref("EventSource/error_event", "error")}} event is dispatched on an <code>EventSource</code> object.</dd>
 <dt>{{domxref("EventSource.onmessage")}}</dt>
 <dd>Is an {{domxref("EventHandler")}} called when a {{domxref("EventSource/message_event", "message")}} event is received, that is when a message is coming from the source.</dd>
 <dt>{{domxref("EventSource.onopen")}}</dt>
 <dd>Is an {{domxref("EventHandler")}} called when an {{domxref("EventSource/open_event", "open")}} event is received, that is when the connection was just opened.</dd>
</dl>

<h2 id="Methods">Methods</h2>

<p><em>This interface also inherits methods from its parent, {{domxref("EventTarget")}}.</em></p>

<dl>
 <dt>{{domxref("EventSource.close()")}}</dt>
 <dd>Closes the connection, if any, and sets the <code>readyState</code> attribute to <code>CLOSED</code>. If the connection is already closed, the method does nothing.</dd>
</dl>

<h2 id="Events">Events</h2>

<dl>
 <dt>{{domxref("EventSource/error_event", "error")}}</dt>
 <dd>Fired when a connection to an event source failed to open.</dd>
 <dt>{{domxref("EventSource/message_event", "message")}}</dt>
 <dd>Fired when data is received from an event source.</dd>
 <dt>{{domxref("EventSource/open_event", "open")}}</dt>
 <dd>Fired when a connection to an event source has opened.</dd>
</dl>

<h2 id="Examples">Examples</h2>

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

<pre class="brush: js">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);
}</pre>

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

<div class="note">
<p><strong>Note</strong>: You can find a full example on GitHub — see <a href="https://github.com/mdn/dom-examples/tree/master/server-sent-events">Simple SSE demo using PHP.</a></p>
</div>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
  </tr>
  <tr>
   <td>{{SpecName('HTML WHATWG', "comms.html#the-eventsource-interface", "EventSource")}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
  </tr>
 </tbody>
</table>

<ul>
</ul>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<div>


<p>{{Compat("api.EventSource")}}</p>
</div>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/Server-sent_events">Server-sent events</a></li>
 <li><a href="/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events">Using server-sent events</a></li>
</ul>