This specification is like no other — it has been processed with you, the humble web developer, in mind.
The focus of this specification is readability and ease of access. Unlike the full HTML Standard, this "developer's edition" removes information that only browser vendors need know. It is automatically produced from the full specification by our build tooling, and thus always in sync with the latest developments in HTML.
To read about its conception, construction, and future, read the original press release, and the blog post about its relaunch.
Finally, feel free to contribute on GitHub to make this edition better for everyone!
Various mechanisms can cause author-provided executable code to run in the context of a document. These mechanisms include, but are probably not limited to:
script
elements.javascript:
URLs.addEventListener()
, by explicit event handler content attributes, by
event handler IDL attributes, or otherwise.The message
attribute must return the
value it was initialized to. It represents the error message.
The filename
attribute must return the
value it was initialized to. It represents the URL of the script in which the error
originally occurred.
The lineno
attribute must return the
value it was initialized to. It represents the line number where the error occurred in the
script.
The colno
attribute must return the value
it was initialized to. It represents the column number where the error occurred in the script.
The error
attribute must return the value
it was initialized to. Where appropriate, it is set to the object representing the error (e.g.,
the exception object in the case of an uncaught DOM exception).
In addition to synchronous runtime script errors, scripts
may experience asynchronous promise rejections, tracked via the unhandledrejection
and rejectionhandled
events.
When the user agent is to notify about rejected promises on a given environment settings object settings object, it must run these steps:
Let list be a copy of settings object's about-to-be-notified rejected promises list.
If list is empty, abort these steps.
Clear settings object's about-to-be-notified rejected promises list.
Queue a task to run the following substep:
For each promise p in list:
If p's [[PromiseIsHandled]] internal slot is true, continue to the next iteration of the loop.
Let notHandled be the result of firing an
event named unhandledrejection
at
settings object's global
object, using PromiseRejectionEvent
, with the cancelable
attribute initialized to true, the promise
attribute initialized to
p, and the reason
attribute
initialized to the value of p's [[PromiseResult]] internal slot.
If notHandled is false, then the promise rejection is handled. Otherwise, the promise rejection is not handled.
If p's [[PromiseIsHandled]] internal slot is false, add p to settings object's outstanding rejected promises weak set.
This algorithm results in promise rejections being marked as handled or not handled. These concepts parallel handled and not handled script errors. If a rejection is still not handled after this, then the rejection may be reported to a developer console.
JavaScript contains an implementation-defined HostPromiseRejectionTracker(promise, operation) abstract operation. User agents must use the following implementation: [JAVASCRIPT]
Let script be the running script.
If script's muted errors is true, terminate these steps.
Let settings object be script's settings object.
If operation is "reject"
,
Add promise to settings object's about-to-be-notified rejected promises list.
If operation is "handle"
,
If settings object's about-to-be-notified rejected promises list contains promise, remove promise from that list and abort these steps.
If settings object's outstanding rejected promises weak set does not contain promise, abort these steps.
Remove promise from settings object's outstanding rejected promises weak set.
Queue a task to fire an event
named rejectionhandled
at settings
object's global object, using
PromiseRejectionEvent
, with the promise
attribute initialized to
promise, and the reason
attribute initialized to the value of promise's [[PromiseResult]] internal
slot.
PromiseRejectionEvent
interfaceThe promise
attribute must
return the value it was initialized to. It represents the promise which this notification is about.
The reason
attribute must
return the value it was initialized to. It represents the rejection reason for the promise.
JavaScript contains an implementation-defined HostEnsureCanCompileStrings(callerRealm, calleeRealm) abstract operation. User agents must use the following implementation: [JAVASCRIPT]
Perform ? EnsureCSPDoesNotBlockStringCompilation(callerRealm, calleeRealm). [CSP]
Many objects can have event handlers specified. These act as non-capture event listeners for the object on which they are specified. [DOM]
An event handler has a name, which always starts with
"on
" and is followed by the name of the event for which it is intended.
An event handler has a value, which is either null, or is
a callback object.
The EventHandler
callback function type describes how this is exposed to scripts.
Event handlers are exposed in one of two ways.
The first way, common to all event handlers, is as an event handler IDL attribute.
The second way is as an event handler content
attribute. Event handlers on HTML elements and some of the event handlers on
Window
objects are exposed in this way.
An event handler content attribute is a content attribute for a specific event handler. The name of the content attribute is the same as the name of the event handler.
Event handler content attributes, when specified, must contain valid JavaScript code which, when parsed, would match the FunctionBody production after automatic semicolon insertion.
This example demonstrates the order in which event listeners are invoked. If the button in this example is clicked by the user, the page will show four alerts, with the text "ONE", "TWO", "THREE", and "FOUR" respectively.
<button id="test">Start Demo</button> <script> var button = document.getElementById('test'); button.addEventListener('click', function () { alert('ONE') }, false); button.setAttribute('onclick', "alert('NOT CALLED')"); // event handler listener is registered here button.addEventListener('click', function () { alert('THREE') }, false); button.onclick = function () { alert('TWO'); }; button.addEventListener('click', function () { alert('FOUR') }, false); </script>
The EventHandler
callback function type represents a callback used for event
handlers.
In JavaScript, any Function
object implements
this interface.
For example, the following document fragment:
<body onload="alert(this)" onclick="alert(this)">
...leads to an alert saying "[object Window]
" when the document is
loaded, and an alert saying "[object HTMLBodyElement]
" whenever the
user clicks something in the page.
The return value of the function affects whether the event is canceled or not: if the return value is false, the event is canceled.
There are two exceptions in the platform, for historical reasons:
The onerror
handlers on global objects, where
returning true cancels the event
The onbeforeunload
handler, where
returning any non-null and non-undefined value will cancel the event.
For historical reasons, the onerror
handler has different
arguments:
window.onerror = (message, source, lineno, colno, error) => { … };
Similarly, the onbeforeunload
handler has a
different return value: it will be cast to a string.
Document
objects, and Window
objectsThe following are the event handlers (and their corresponding event handler event types)
supported by all HTML elements, as both event handler content attributes
and event handler IDL attributes; and
supported by all Document
and Window
objects, as event handler IDL
attributes:
Event handler | Event handler event type |
---|---|
onabort | abort
|
onauxclick | auxclick
|
oncancel | cancel
|
oncanplay | canplay
|
oncanplaythrough | canplaythrough
|
onchange | change
|
onclick | click
|
onclose | close
|
oncontextmenu | contextmenu
|
oncuechange | cuechange
|
ondblclick | dblclick
|
ondrag | drag
|
ondragend | dragend
|
ondragenter | dragenter
|
ondragexit | dragexit
|
ondragleave | dragleave
|
ondragover | dragover
|
ondragstart | dragstart
|
ondrop | drop
|
ondurationchange | durationchange
|
onemptied | emptied
|
onended | ended
|
oninput | input
|
oninvalid | invalid
|
onkeydown | keydown
|
onkeypress | keypress
|
onkeyup | keyup
|
onloadeddata | loadeddata
|
onloadedmetadata | loadedmetadata
|
onloadend | loadend
|
onloadstart | loadstart
|
onmousedown | mousedown
|
onmouseenter | mouseenter
|
onmouseleave | mouseleave
|
onmousemove | mousemove
|
onmouseout | mouseout
|
onmouseover | mouseover
|
onmouseup | mouseup
|
onwheel | wheel
|
onpause | pause
|
onplay | play
|
onplaying | playing
|
onprogress | progress
|
onratechange | ratechange
|
onreset | reset
|
onsecuritypolicyviolation | securitypolicyviolation
|
onseeked | seeked
|
onseeking | seeking
|
onselect | select
|
onstalled | stalled
|
onsubmit | submit
|
onsuspend | suspend
|
ontimeupdate | timeupdate
|
ontoggle | toggle
|
onvolumechange | volumechange
|
onwaiting | waiting
|
The following are the event handlers (and their corresponding event handler event types)
supported by all HTML elements other than body
and frameset
elements, as both event handler content attributes and event handler IDL
attributes; supported by all Document
objects, as event handler IDL attributes; and
supported by all Window
objects, as event handler IDL attributes on the
Window
objects themselves, and with corresponding event handler content
attributes and event handler IDL attributes exposed on all body
and frameset
elements that are owned by that Window
object's associated Document
:
Event handler | Event handler event type |
---|---|
onblur | blur
|
onerror | error
|
onfocus | focus
|
onload | load
|
onresize | resize
|
onscroll | scroll
|
The following are the event handlers (and their corresponding event handler event types)
supported by Window
objects, as event handler IDL attributes on the
Window
objects themselves, and with corresponding event handler content
attributes and event handler IDL attributes exposed on all body
and frameset
elements that are owned by that Window
object's associated Document
:
Event handler | Event handler event type |
---|---|
onafterprint | afterprint
|
onbeforeprint | beforeprint
|
onbeforeunload | beforeunload
|
onhashchange | hashchange
|
onlanguagechange | languagechange
|
onmessage | message
|
onmessageerror | messageerror
|
onoffline | offline
|
ononline | online
|
onpagehide | pagehide
|
onpageshow | pageshow
|
onpopstate | popstate
|
onrejectionhandled | rejectionhandled
|
onstorage | storage
|
onunhandledrejection | unhandledrejection
|
onunload | unload
|
The following are the event handlers (and their corresponding event handler event types)
supported by all HTML elements, as both event handler content attributes
and event handler IDL attributes; and
supported by all Document
objects, as event handler IDL attributes:
Event handler | Event handler event type |
---|---|
oncut | cut
|
oncopy | copy
|
onpaste | paste
|
The following are the event handlers (and their corresponding event handler event types)
supported on Document
objects as event handler IDL attributes:
Event handler | Event handler event type |
---|---|
onreadystatechange | readystatechange
|
WindowOrWorkerGlobalScope
mixinThe WindowOrWorkerGlobalScope
mixin is for use of APIs that are to be exposed on
Window
and WorkerGlobalScope
objects.
Other standards are encouraged to further extend it using partial
interface WindowOrWorkerGlobalScope { … };
along with an appropriate
reference.
origin
Returns the global object's origin, serialized as string.
Developers are strongly encouraged to use self.origin
over location.origin
. The former returns the origin of the environment,
the latter of the URL of the environment. Imagine the following script executing in a document on
https://stargate.example/
:
var frame = document.createElement("iframe") frame.onload = function() { var frameWin = frame.contentWindow console.log(frameWin.location.origin) // "null" console.log(frameWin.origin) // "https://stargate.example" } document.body.appendChild(frame)
self.origin
is a more reliable security indicator.
The origin
attribute's getter must return this
object's relevant settings object's origin, serialized.
The atob()
and btoa()
methods
allow developers to transform content to and from the base64 encoding.
In these APIs, for mnemonic purposes, the "b" can be considered to stand for "binary", and the "a" for "ASCII". In practice, though, for primarily historical reasons, both the input and output of these functions are Unicode strings.
btoa
( data )Takes the input data, in the form of a Unicode string containing only characters in the range U+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, and converts it to its base64 representation, which it returns.
Throws an "InvalidCharacterError
" DOMException
exception if the input string contains any out-of-range characters.
atob
( data )Takes the input data, in the form of a Unicode string containing base64-encoded binary data, decodes it, and returns a string consisting of characters in the range U+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, corresponding to that binary data.
Throws an "InvalidCharacterError
" DOMException
if the
input string is not valid base64 data.