1. 8 Web application APIs
    1. 8.1 Scripting
      1. 8.1.1 Introduction
        1. 8.1.1.1 Integration with the JavaScript module system
        2. 8.1.1.2 Runtime script errors
        3. 8.1.1.3 Unhandled promise rejections
      2. 8.1.2 Event loops
      3. 8.1.3 Events
        1. 8.1.3.1 Event handlers
        2. 8.1.3.2 Event handlers on elements, Document objects, and Window objects
    2. 8.2 The WindowOrWorkerGlobalScope mixin
    3. 8.3 Base64 utility methods

8 Web application APIs

8.1 Scripting

8.1.1 Introduction

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:

8.1.1.1 Integration with the JavaScript module system

The JavaScript specification defines a syntax for modules, as well as some host-agnostic parts of their processing model. This specification defines the rest of their processing model: how the module system is bootstrapped, via the script element with type attribute set to "module", and how modules are fetched, resolved, and executed. [JAVASCRIPT]

Although the JavaScript specification speaks in terms of "scripts" versus "modules", in general this specification speaks in terms of classic scripts versus module scripts, since both of them use the script element.

modulePromise = import(specifier)

Returns a promise for the module namespace object for the module script identified by specifier. This allows dynamic importing of module scripts at runtime, instead of statically using the import statement form. The specifier will be resolved relative to the active script's base URL.

The returned promise will be rejected if an invalid specifier is given, or if a failure is encountered while fetching or evaluating the resulting module graph.

This syntax can be used inside both classic and module scripts. It thus provides a bridge into the module-script world, from the classic-script world.

url = import . meta . url

Returns the active module script's base URL.

This syntax can only be used inside module scripts.

Module maps are used to ensure that imported JavaScript modules are only fetched, parsed, and evaluated once per Document or worker.

Since module maps are keyed by URL, the following code will create three separate entries in the module map, since it results in three different URLs:

import "https://example.com/module.mjs";
import "https://example.com/module.mjs#map-buster";
import "https://example.com/module.mjs?debug=true";

That is, URL queries and fragments can be varied to create distinct entries in the module map; they are not ignored. Thus, three separate fetches and three separate module evaluations will be performed.

In contrast, the following code would only create a single entry in the module map, since after applying the URL parser to these inputs, the resulting URL records are equal:

import "https://example.com/module2.mjs";
import "https:example.com/module2.mjs";
import "https://///example.com\\module2.mjs";
import "https://example.com/foo/../module2.mjs";

So in this second example, only one fetch and one module evaluation will occur.

Note that this behavior is the same as how shared workers are keyed by their parsed constructor url.

The following are valid module specifiers:

The following are valid module specifiers according to the above algorithm, but will invariably cause failures when they are fetched:

The following are not valid module specifiers according to the above algorithm:

8.1.1.2 Runtime script errors

In various scenarios, the user agent can report an exception by firing an error event at the Window. If this event is not canceled, then the error is considered not handled, and can be reported to the developer console.

8.1.1.3 Unhandled promise rejections

In addition to synchronous runtime script errors, scripts may experience asynchronous promise rejections, tracked via the unhandledrejection and rejectionhandled events.

Support: unhandledrejectionChrome for Android 70+Chrome 49+iOS Safari 11.3+UC Browser for Android 11.8+Firefox NoneIE NoneOpera Mini NoneSafari 11+Edge NoneOpera 36+Samsung Internet 5+Android Browser 67+

Source: caniuse.com

8.1.2 Event loops

To coordinate events, user interaction, scripts, rendering, networking, and so forth, user agents must use event loops as described in this section. There are two kinds of event loops: those for browsing contexts, and those for workers.

There must be at least one browsing context event loop per user agent, and at most one per unit of related similar-origin browsing contexts.

When there is more than one event loop for a unit of related browsing contexts, complications arise when a browsing context in that group is navigated such that it switches from one unit of related similar-origin browsing contexts to another. This specification does not currently describe how to handle these complications.

A browsing context event loop always has at least one browsing context. If such an event loop's browsing contexts all go away, then the event loop goes away as well. A browsing context always has an event loop coordinating its activities.

Worker event loops are simpler: each worker has one event loop, and the worker processing model manages the event loop's lifetime.

8.1.3 Events

8.1.3.1 Event handlers

Many objects can have event handlers specified. These act as non-capture event listeners for the object on which they are specified. [DOM]

Event handlers are exposed in 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.

For both of these two ways, the event handler is exposed through a name, which is a string that always starts with "on" and is followed by the name of the event for which the handler is intended.


Most of the time, the object that exposes an event handler is the same as the object on which the corresponding event listener is added. However, the body and frameset elements expose several event handlers that act upon the element's Window object, if one exists. In either case, we call the object an event handler acts upon the target of that event handler.


An event handler IDL attribute is an IDL attribute for a specific event handler. The name of the IDL attribute is the same as the name of the event handler.


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>

However, in the following example, the event handler is deactivated after its initial activation (and its event listener is removed), before being reactivated at a later time. The page will show five alerts with "ONE", "TWO", "THREE", "FOUR", and "FIVE" respectively, in order.

<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 is activated here
 button.addEventListener('click', function () { alert('TWO') }, false);
 button.onclick = null;                                 // but deactivated here
 button.addEventListener('click', function () { alert('THREE') }, false);
 button.onclick = function () { alert('FOUR'); };       // and re-activated here
 button.addEventListener('click', function () { alert('FIVE') }, 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:

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.

8.1.3.2 Event handlers on elements, Document objects, and Window objects

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 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

We call the set of the names of the event handlers listed in the first column of this table the Window-reflecting body element event handler set.


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

8.2 The WindowOrWorkerGlobalScope mixin

The 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 mixin WindowOrWorkerGlobalScope { … }; along with an appropriate reference.

origin = self . 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.

8.3 Base64 utility methods

Support: atob-btoaChrome for Android 70+Chrome 4+iOS Safari 3.2+UC Browser for Android 11.8+Firefox 2+IE 10+Opera Mini all+Safari 3.1+Edge 12+Opera 10.6+Samsung Internet 4+Android Browser 2.1+

Source: caniuse.com

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.

result = self . 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.

result = self . 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.