1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
---
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>
|
