HTML

Living Standard — Last Updated 20 May 2022

    1. 4.12 Scripting
      1. 4.12.1 The script element
        1. 4.12.1.1 Processing model
        2. 4.12.1.2 Scripting languages
        3. 4.12.1.3 Restrictions for contents of script elements
        4. 4.12.1.4 Inline documentation for external scripts
        5. 4.12.1.5 Interaction of script elements and XSLT
      2. 4.12.2 The noscript element
      3. 4.12.3 The template element
        1. 4.12.3.1 Interaction of template elements with XSLT and XPath
      4. 4.12.4 The slot element

4.12 Scripting

Scripts allow authors to add interactivity to their documents.

Authors are encouraged to use declarative alternatives to scripting where possible, as declarative mechanisms are often more maintainable, and many users disable scripting.

For example, instead of using a script to show or hide a section to show more details, the details element could be used.

Authors are also encouraged to make their applications degrade gracefully in the absence of scripting support.

For example, if an author provides a link in a table header to dynamically resort the table, the link could also be made to function without scripts by requesting the sorted table from the server.

4.12.1 The script element

Element/script

Support in all current engines.

Firefox1+SafariYesChrome1+
OperaYesEdge79+
Edge (Legacy)12+Internet ExplorerYes
Firefox Android4+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

HTMLScriptElement

Support in all current engines.

Firefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android4+Safari iOS1+Chrome Android18+WebView Android1+Samsung Internet1.0+Opera Android12.1+
Categories:
Metadata content.
Flow content.
Phrasing content.
Script-supporting element.
Contexts in which this element can be used:
Where metadata content is expected.
Where phrasing content is expected.
Where script-supporting elements are expected.
Content model:
If there is no src attribute, depends on the value of the type attribute, but must match script content restrictions.
If there is a src attribute, the element must be either empty or contain only script documentation that also matches script content restrictions.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
src — Address of the resource
type — Type of script
nomodule — Prevents execution in user agents that support module scripts
async — Execute script when available, without blocking while fetching
defer — Defer script execution
crossorigin — How the element handles crossorigin requests
integrity — Integrity metadata used in Subresource Integrity checks [SRI]
referrerpolicyReferrer policy for fetches initiated by the element
blocking — Whether the element is potentially render-blocking
Accessibility considerations:
For authors.
For implementers.
DOM interface:
[Exposed=Window]
interface HTMLScriptElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions] attribute USVString src;
  [CEReactions] attribute DOMString type;
  [CEReactions] attribute boolean noModule;
  [CEReactions] attribute boolean async;
  [CEReactions] attribute boolean defer;
  [CEReactions] attribute DOMString? crossOrigin;
  [CEReactions] attribute DOMString text;
  [CEReactions] attribute DOMString integrity;
  [CEReactions] attribute DOMString referrerPolicy;
  [SameObject, PutForwards=value] readonly attribute DOMTokenList blocking;

  static boolean supports(DOMString type);

  // also has obsolete members
};

The script element allows authors to include dynamic script and data blocks in their documents. The element does not represent content for the user.

Element/script#attr-type

Support in all current engines.

Firefox1+SafariYesChrome1+
OperaYesEdge79+
Edge (Legacy)12+Internet ExplorerYes
Firefox Android4+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

The type attribute allows customization of the type of script represented:

The requirement that data blocks must be denoted using a valid MIME type string is in place to avoid potential future collisions. If this specification ever adds additional types of script, they will be triggered by setting the type attribute to something which is not a MIME type, like how the "module" value denotes module scripts. By using a valid MIME type string now, you ensure that your data block will not ever be reinterpreted as a different script type, even in future user agents.

Classic scripts and JavaScript module scripts can be embedded inline, or be imported from an external file using the src attribute, which if specified gives the URL of the external script resource to use. If src is specified, it must be a valid non-empty URL potentially surrounded by spaces.

The contents of inline script elements, or the external script resource, must conform with the requirements of the JavaScript specification's Script or Module productions, for classic scripts and JavaScript module scripts respectively. [JAVASCRIPT]

The contents of the external script resource for CSS module scripts must conform to the requirements of the CSS specification. [CSS]

The contents of the external script resource for JSON module scripts must conform to the requirements of the JSON specification [JSON].

When used to include data blocks, the data must be embedded inline, the format of the data must be given using the type attribute, and the contents of the script element must conform to the requirements defined for the format used. The src, async, nomodule, defer, crossorigin, integrity, and referrerpolicy attributes must not be specified.

The nomodule attribute is a boolean attribute that prevents a script from being executed in user agents that support module scripts. This allows selective execution of module scripts in modern user agents and classic scripts in older user agents, as shown below. The nomodule attribute must not be specified on module scripts (and will be ignored if it is).

Element/script#attr-async

Support in all current engines.

Firefox1+SafariYesChrome1+
OperaYesEdge79+
Edge (Legacy)12+Internet ExplorerYes
Firefox Android4+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

Element/script#attr-defer

Support in all current engines.

Firefox3.5+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet Explorer10+
Firefox Android4+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes

The async and defer attributes are boolean attributes that indicate how the script should be evaluated. Classic scripts may specify defer or async, but must not specify either unless the src attribute is present. Module scripts may specify the async attribute, but must not specify the defer attribute.

There are several possible modes that can be selected using these attributes, and depending on the script's type.

For classic scripts, if the async attribute is present, then the classic script will be fetched in parallel to parsing and evaluated as soon as it is available (potentially before parsing completes). If the async attribute is not present but the defer attribute is present, then the classic script will be fetched in parallel and evaluated when the page has finished parsing. If neither attribute is present, then the script is fetched and evaluated immediately, blocking parsing until these are both complete.

For module scripts, if the async attribute is present, then the module script and all its dependencies will be fetched in parallel to parsing, and the module script will be evaluated as soon as it is available (potentially before parsing completes). Otherwise, the module script and its dependencies will be fetched in parallel to parsing and evaluated when the page has finished parsing. (The defer attribute has no effect on module scripts.)

This is all summarized in the following schematic diagram:

With <script>, parsing is interrupted by fetching and execution. With <script defer>, fetching is parallel to parsing and execution takes place after all parsing has finished. And with <script async>, fetching is parallel to parsing but once it finishes parsing is interrupted to execute the script. The story for <script type="module"> is similar to <script defer>, but the dependencies will be fetched as well, and the story for <script type="module" async> is similar to <script async> with the extra dependency fetching.

The exact processing details for these attributes are, for mostly historical reasons, somewhat non-trivial, involving a number of aspects of HTML. The implementation requirements are therefore by necessity scattered throughout the specification. The algorithms below (in this section) describe the core of this processing, but these algorithms reference and are referenced by the parsing rules for script start and end tags in HTML, in foreign content, and in XML, the rules for the document.write() method, the handling of scripting, etc.

The defer attribute may be specified even if the async attribute is specified, to cause legacy web browsers that only support defer (and not async) to fall back to the defer behavior instead of the blocking behavior that is the default.

The crossorigin attribute is a CORS settings attribute. For classic scripts, it controls whether error information will be exposed, when the script is obtained from other origins. For module scripts, it controls the credentials mode used for cross-origin requests.

Unlike classic scripts, module scripts require the use of the CORS protocol for cross-origin fetching.

The integrity attribute represents the integrity metadata for requests which this element is responsible for. The value is text. The integrity attribute must not be specified when the src attribute is not specified. [SRI]

The referrerpolicy attribute is a referrer policy attribute. Its purpose is to set the referrer policy used when fetching the script, as well as any scripts imported from it. [REFERRERPOLICY]

An example of a script element's referrer policy being used when fetching imported scripts but not other subresources:

<script referrerpolicy="origin">
  fetch('/api/data');    // not fetched with <script>'s referrer policy
  import('./utils.mjs'); // is fetched with <script>'s referrer policy ("origin" in this case)
</script>

The blocking attribute is a blocking attribute.

Changing the src, type, nomodule, async, defer, crossorigin, integrity, and referrerpolicy attributes dynamically has no direct effect; these attributes are only used at specific times described below.

The IDL attributes src, type, defer, integrity, and blocking, must each reflect the respective content attributes of the same name.

HTMLScriptElement/referrerPolicy

Support in all current engines.

Firefox65+Safari14+Chrome70+
Opera57+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android65+Safari iOS14+Chrome Android70+WebView Android70+Samsung Internet10.0+Opera Android49+

The referrerPolicy IDL attribute must reflect the referrerpolicy content attribute, limited to only known values.

The crossOrigin IDL attribute must reflect the crossorigin content attribute, limited to only known values.

The noModule IDL attribute must reflect the nomodule content attribute.

The async getter steps are:

  1. If this's force async is true, then return true.

  2. If this's async content attribute is present, then return true.

  3. Return false.

The async setter steps are:

  1. Set this's force async to false.

  2. If the given value is true, then set this's async content attribute to the empty string.

  3. Otherwise, remove this's async content attribute.

script.text [ = value ]

Returns the child text content of the element.

Can be set, to replace the element's children with the given value.

HTMLScriptElement.supports(type)

Returns true if the given type is a script type supported by the user agent. The possible script types in this specification are "classic" and "module", but others might be added in the future.

The text attribute's getter must return this script element's child text content.

The text attribute's setter must string replace all with the given value within this script element.

When inserted using the document.write() method, script elements usually execute (typically blocking further script execution or HTML parsing). When inserted using the innerHTML and outerHTML attributes, they do not execute at all.

HTMLScriptElement/supports

Firefox94+SafariNoChrome97+
Opera83+Edge97+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android94+Safari iOSNoChrome Android97+WebView Android97+Samsung InternetNoOpera AndroidNo

The supports(type) method steps are:

  1. If type is "classic", then return true.

  2. If type is "module", then return true.

  3. Return false.

The type argument has to exactly match these values; we do not perform an ASCII case-insensitive match. This is different from how type content attribute values are treated, and how method works, but it aligns with the WorkerType enumeration used in the Worker() constructor.

In this example, two script elements are used. One embeds an external classic script, and the other includes some data as a data block.

<script src="game-engine.js"></script>
<script type="text/x-game-map">
........U.........e
o............A....e
.....A.....AAA....e
.A..AAA...AAAAA...e
</script>

The data in this case might be used by the script to generate the map of a video game. The data doesn't have to be used that way, though; maybe the map data is actually embedded in other parts of the page's markup, and the data block here is just used by the site's search engine to help users who are looking for particular features in their game maps.

The following sample shows how a script element can be used to define a function that is then used by other parts of the document, as part of a classic script. It also shows how a script element can be used to invoke script while the document is being parsed, in this case to initialize the form's output.

<script>
 function calculate(form) {
   var price = 52000;
   if (form.elements.brakes.checked)
     price += 1000;
   if (form.elements.radio.checked)
     price += 2500;
   if (form.elements.turbo.checked)
     price += 5000;
   if (form.elements.sticker.checked)
     price += 250;
   form.elements.result.value = price;
 }
</script>
<form name="pricecalc" onsubmit="return false" onchange="calculate(this)">
 <fieldset>
  <legend>Work out the price of your car</legend>
  <p>Base cost: £52000.</p>
  <p>Select additional options:</p>
  <ul>
   <li><label><input type=checkbox name=brakes> Ceramic brakes (£1000)</label></li>
   <li><label><input type=checkbox name=radio> Satellite radio (£2500)</label></li>
   <li><label><input type=checkbox name=turbo> Turbo charger (£5000)</label></li>
   <li><label><input type=checkbox name=sticker> "XZ" sticker (£250)</label></li>
  </ul>
  <p>Total: £<output name=result></output></p>
 </fieldset>
 <script>
  calculate(document.forms.pricecalc);
 </script>
</form>

The following sample shows how a script element can be used to include an external JavaScript module script.

<script type="module" src="app.mjs"></script>

This module, and all its dependencies (expressed through JavaScript import statements in the source file), will be fetched. Once the entire resulting module graph has been imported, and the document has finished parsing, the contents of app.mjs will be evaluated.

Additionally, if code from another script element in the same Window imports the module from app.mjs (e.g. via import "./app.mjs";), then the same JavaScript module script created by the former script element will be imported.

This example shows how to include a JavaScript module script for modern user agents, and a classic script for older user agents:

<script type="module" src="app.mjs"></script>
<script nomodule defer src="classic-app-bundle.js"></script>

In modern user agents that support JavaScript module scripts, the script element with the nomodule attribute will be ignored, and the script element with a type of "module" will be fetched and evaluated (as a JavaScript module script). Conversely, older user agents will ignore the script element with a type of "module", as that is an unknown script type for them — but they will have no problem fetching and evaluating the other script element (as a classic script), since they do not implement the nomodule attribute.

The following sample shows how a script element can be used to write an inline JavaScript module script that performs a number of substitutions on the document's text, in order to make for a more interesting reading experience (e.g. on a news site): [XKCD1288]

<script type="module">
 import { walkAllTextNodeDescendants } from "./dom-utils.mjs";

 const substitutions = new Map([
   ["witnesses", "these dudes I know"]
   ["allegedly", "kinda probably"]
   ["new study", "Tumblr post"]
   ["rebuild", "avenge"]
   ["space", "spaaace"]
   ["Google glass", "Virtual Boy"]
   ["smartphone", "Pokédex"]
   ["electric", "atomic"]
   ["Senator", "Elf-Lord"]
   ["car", "cat"]
   ["election", "eating contest"]
   ["Congressional leaders", "river spirits"]
   ["homeland security", "Homestar Runner"]
   ["could not be reached for comment", "is guilty and everyone knows it"]
 ]);

 function substitute(textNode) {
   for (const [before, after] of substitutions.entries()) {
     textNode.data = textNode.data.replace(new RegExp(`\\b${before}\\b`, "ig"), after);
   }
 }

 walkAllTextNodeDescendants(document.body, substitute);
</script>

Some notable features gained by using a JavaScript module script include the ability to import functions from other JavaScript modules, strict mode by default, and how top-level declarations do not introduce new properties onto the global object. Also note that no matter where this script element appears in the document, it will not be evaluated until both document parsing has complete and its dependency (dom-utils.mjs) has been fetched and evaluated.

The following sample shows how a JSON module script can be imported from inside a JavaScript module script:

<script type="module">
 import peopleInSpace from "http://api.open-notify.org/astros.json" assert { type: "json" };

 const list = document.querySelector("#people-in-space");
 for (const { craft, name } of peopleInSpace.people) {
   const li = document.createElement("li");
   li.textContent = `${name} / ${craft}`;
   list.append(li);
 }
</script>

MIME type checking for module scripts is strict. In order for the fetch of the JSON module script to succeed, the HTTP response must have a JSON MIME type, for example Content-Type: text/json. On the other hand, if the assert { type: "json" } part of the statement is omitted, it is assumed that the intent is to import a JavaScript module script, and the fetch will fail if the HTTP response has a MIME type that is not a JavaScript MIME type.

4.12.1.1 Processing model

A script element has several associated pieces of state.

A script element has a parser document, which is either null or a Document, initially null. It is set by the HTML parser and the XML parser on script elements they insert, and affects the processing of those elements. script elements with non-null parser documents are known as parser-inserted.

A script element has a preparation-time document, which is either null or a Document, initially null. It is used to prevent scripts that move between documents during preparation from executing.

A script element has a force async boolean, initially true. It is set to false by the HTML parser and the XML parser on script elements they insert, and when the element gets an async content attribute added.

A script element has a from an external file boolean, initially false. It is determined when the script is prepared, based on the src attribute of the element at that time.

A script element has a ready to be parser-executed boolean, initially false. This is used only used for elements that are also parser-inserted, to let the parser know when to execute the script.

A script element has an already started boolean, initially false.

A script element has a delaying the load event boolean, initially false.

A script element has a type, which is either null, "classic", or "module", initially null. It is determined when the element is prepared, based on the type attribute of the element at that time.

A script element has a result, which is either "uninitialized", null (representing an error), or a script. It is initially "uninitialized".

A script element has steps to run when the result is ready, which are a series of steps or null, initially null. To mark as ready a script element el given a script-or-null result:

  1. Set el's result to result.

  2. If el's steps to run when the result is ready are not null, then run them.

  3. Set el's steps to run when the result is ready to null.

  4. Set el's delaying the load event to false.


A script element el is implicitly potentially render-blocking if el's type is "classic", el is parser-inserted, and el does not have an async or defer attribute.

The cloning steps for a script element el being cloned to a copy copy are to set copy's already started to el's already started.

When an async attribute is added to a script element el, the user agent must set el's force async to false.

Whenever a script element el's delaying the load event is true, the user agent must delay the load event of el's preparation-time document.


When a script element el that is not parser-inserted experiences one of the events listed in the following list, the user agent must immediately prepare the script element el:

To prepare the script element given a script element el:

  1. If el's already started is true, then return.

  2. Let parser document be el's parser document.

  3. Set el's parser document to null.

    This is done so that if parser-inserted script elements fail to run when the parser tries to run them, e.g. because they are empty or specify an unsupported scripting language, another script can later mutate them and cause them to run again.

  4. If parser document is non-null and el does not have an async attribute, then set el's force async to true.

    This is done so that if a parser-inserted script element fails to run when the parser tries to run it, but it is later executed after a script dynamically updates it, it will execute in an async fashion even if the async attribute isn't set.

  5. Let source text be el's child text content.

  6. If el has no src attribute, and source text is the empty string, then return.

  7. If el is not connected, then return.

  8. If any of the following are true:

    then let the script block's type string for this script element be "text/javascript".

    Otherwise, if el has a type attribute, then let the script block's type string be the value of that attribute.

    Otherwise, el has a non-empty language attribute; let the script block's type string be the concatenation of "text/" and the value of el's language attribute.

    The language attribute is never conforming, and is always ignored if there is a type attribute present.

  9. If the script block's type string with leading and trailing ASCII whitespace stripped is a JavaScript MIME type essence match, then set el's type to "classic".

  10. Otherwise, if the script block's type string is an ASCII case-insensitive match for the string "module", then set el's type to "module".

  11. Otherwise, return. (No script is executed, and el's type is left as null.)

  12. If parser document is non-null, then set el's parser document back to parser document and set el's force async to false.

  13. Set el's already started to true.

  14. Set el's preparation-time document to its node document.

  15. If parser document is non-null, and parser document is not equal to el's preparation-time document, then return.

  16. If scripting is disabled for el, then return.

    The definition of scripting is disabled means that, amongst others, the following scripts will not execute: scripts in DOMParser-created documents, scripts in documents created by XSLTProcessor's transformToDocument feature, and scripts that are first inserted by a script into a Document that was created using the API. [XHR] [DOMPARSING] [XSLTP] [DOM]

  17. If el has a nomodule content attribute and its type is "classic", then return.

    This means specifying nomodule on a module script has no effect; the algorithm continues onward.

  18. If el does not have a src content attribute, and the Should element's inline behavior be blocked by Content Security Policy? algorithm returns "Blocked" when given el, "script", and source text, then return. [CSP]

  19. If el has an event attribute and a for attribute, and el's type is "classic", then:

    1. Let for be the value of el's' for attribute.

    2. Let event be the value of el's event attribute.

    3. Strip leading and trailing ASCII whitespace from event and for.

    4. If for is not an ASCII case-insensitive match for the string "window", then return.

    5. If event is not an ASCII case-insensitive match for either the string "onload" or the string "onload()", then return.

  20. If el has a charset attribute, then let encoding be the result of getting an encoding from the value of the charset attribute.

    If el does not have a charset attribute, or if getting an encoding failed, then let encoding be el's node document's the encoding.

    If el's type is "module", this encoding will be ignored.

  21. Let classic script CORS setting be the current state of el's crossorigin content attribute.

  22. Let module script credentials mode be the CORS settings attribute credentials mode for el's crossorigin content attribute.

  23. Let cryptographic nonce be el's [[CryptographicNonce]] internal slot's value.

  24. If el has an integrity attribute, then let integrity metadata be that attribute's value.

    Otherwise, let integrity metadata be the empty string.

  25. Let referrer policy be the current state of el's referrerpolicy content attribute.

  26. Let parser metadata be "parser-inserted" if el is parser-inserted, and "not-parser-inserted" otherwise.

  27. Let options be a script fetch options whose cryptographic nonce is cryptographic nonce, integrity metadata is integrity metadata, parser metadata is parser metadata, credentials mode is module script credentials mode, and referrer policy is referrer policy.

  28. Let settings object be el's node document's relevant settings object.

  29. If el has a src content attribute, then:

    1. Let src be the value of el's src attribute.

    2. If src is the empty string, then queue a task to fire an event named error at el, and return.

    3. Set el's from an external file to true.

    4. Parse src relative to el's node document.

    5. If the previous step failed, queue a task to fire an event named error at el, and return. Otherwise, let url be the resulting URL record.

    6. If el is potentially render-blocking, then block rendering on el.

    7. Set el's delaying the load event to true.

    8. Switch on el's type:

      "classic"

      Fetch a classic script given url, settings object, options, classic script CORS setting, and encoding.

      "module"

      Fetch an external module script graph given url, settings object, and options.

      When the chosen algorithm asynchronously completes with result, mark as ready el given result.

      For performance reasons, user agents may start fetching the classic script or module graph (as defined above) as soon as the src attribute is set, instead, in the hope that el will be inserted into the document (and that the crossorigin attribute won't change value in the meantime). Either way, once el is inserted into the document, the load must have started as described in this step. If the UA performs such prefetching, but el is never inserted in the document, or the src attribute is dynamically changed, or the crossorigin attribute is dynamically changed, then the user agent will not execute the script so obtained, and the fetching process will have been effectively wasted.

  30. If el does not have a src content attribute:

    1. Let base URL be el's node document's document base URL.

    2. Switch on el's type:

      "classic"
      1. Let script be the result of creating a classic script using source text, settings object, base URL, and options.

      2. Mark as ready el given script.

      "module"
      1. Set el's delaying the load event to true.

      2. Fetch an inline module script graph, given source text, base URL, settings object, and options. When this asynchronously completes with result, mark as ready el given result.

  31. If el's type is "classic" and el has a src attribute, or el's type is "module":

    1. Assert: el's result is "uninitialized".

    2. If el has an async attribute or el's force async is true:

      1. Let scripts be el's preparation-time document's set of scripts that will execute as soon as possible.

      2. Append el to scripts.

      3. Set el's steps to run when the result is ready to the following:

        1. Execute the script element el.

        2. Remove el from scripts.

    3. Otherwise, if el is not parser-inserted:

      1. Let scripts be el's preparation-time document's list of scripts that will execute in order as soon as possible.

      2. Append el to scripts.

      3. Set el's steps to run when the result is ready to the following:

        1. If scripts[0] is not el, then abort these steps.

        2. While scripts is not empty, and scripts[0]'s result is not "uninitialized":

          1. Execute the script element scripts[0].

          2. Remove scripts[0].

    4. Otherwise, if el has a defer attribute or el's type is "module":

      1. Append el to its parser document's list of scripts that will execute when the document has finished parsing.

      2. Set el's steps to run when the result is ready to the following: set el's ready to be parser-executed to true. (The parser will handle executing the script.)

    5. Otherwise:

      1. Set el's parser document's pending parsing-blocking script to el.

      2. Block rendering on el.

      3. Set el's steps to run when the result is ready to the following: set el's ready to be parser-executed to true. (The parser will handle executing the script.)

  32. Otherwise:

    1. Assert: el's result is not "uninitialized".

    2. If el is parser-inserted, and either the parser that created el is an XML parser or it's an HTML parser whose script nesting level is not greater than one, and el's parser document has a style sheet that is blocking scripts:

      1. Set el's parser document's pending parsing-blocking script to el.

      2. Set el's ready to be parser-executed to true. (The parser will handle executing the script.)

    3. Otherwise, immediately execute the script element el, even if other scripts are already executing.

Each Document has a pending parsing-blocking script, which is a script element or null, initially null.

Each Document has a set of scripts that will execute as soon as possible, which is a set of script elements, initially empty.

Each Document has a list of scripts that will execute in order as soon as possible, which is a list of script elements, initially empty.

Each Document has a list of scripts that will execute when the document has finished parsing, which is a list of script elements, initially empty.

If a script element that blocks a parser gets moved to another Document before it would normally have stopped blocking that parser, it nonetheless continues blocking that parser until the condition that causes it to be blocking the parser no longer applies (e.g., if the script is a pending parsing-blocking script because the original Document has a style sheet that is blocking scripts when it was parsed, but then the script is moved to another Document before the blocking style sheet(s) loaded, the script still blocks the parser until the style sheets are all loaded, at which time the script executes and the parser is unblocked).

To execute the script element given a script element el:

  1. Let document be el's node document.

  2. If el's preparation-time document is not equal to document, then return.

  3. Unblock rendering on el.

  4. If el's result is null, then fire an event named error at el, and return.

  5. If el's from an external file is true, or el's type is "module", then increment document's ignore-destructive-writes counter.

  6. Switch on el's type:

    "classic"
    1. Let oldCurrentScript be the value to which document's currentScript object was most recently set.

    2. If el's root is not a shadow root, then set document's currentScript attribute to el. Otherwise, set it to null.

      This does not use the in a document tree check, as el could have been removed from the document prior to execution, and in that scenario currentScript still needs to point to it.

    3. Run the classic script given by el's result.

    4. Set document's currentScript attribute to oldCurrentScript.

    "module"
    1. Assert: document's currentScript attribute is null.

    2. Run the module script given by el's result.

  7. Decrement the ignore-destructive-writes counter of document, if it was incremented in the earlier step.

  8. If el's from an external file is true, then fire an event named load at el.

4.12.1.2 Scripting languages

User agents are not required to support JavaScript. This standard needs to be updated if a language other than JavaScript comes along and gets similar wide adoption by web browsers. Until such a time, implementing other languages is in conflict with this standard, given the processing model defined for the script element.

Servers should use text/javascript for JavaScript resources, in accordance with Updates to ECMAScript Media Types. Servers should not use other JavaScript MIME types for JavaScript resources, and must not use non-JavaScript MIME types. [RFC9239]

For external JavaScript resources, MIME type parameters in `Content-Type` headers are generally ignored. (In some cases the `charset` parameter has an effect.) However, for the script element's type attribute they are significant; it uses the JavaScript MIME type essence match concept.

For example, scripts with their type attribute set to "text/javascript; charset=utf-8" will not be evaluated, even though that is a valid JavaScript MIME type when parsed.

Furthermore, again for external JavaScript resources, special considerations apply around `Content-Type` header processing as detailed in the prepare the script element algorithm and Fetch. [FETCH]

4.12.1.3 Restrictions for contents of script elements

The easiest and safest way to avoid the rather strange restrictions described in this section is to always escape an ASCII case-insensitive match for "<!--" as "\x3C!--", "<script" as "\x3Cscript", and "</script" as "\x3C/script" when these sequences appear in literals in scripts (e.g. in strings, regular expressions, or comments), and to avoid writing code that uses such constructs in expressions. Doing so avoids the pitfalls that the restrictions in this section are prone to triggering: namely, that, for historical reasons, parsing of script blocks in HTML is a strange and exotic practice that acts unintuitively in the face of these sequences.

The script element's descendant text content must match the script production in the following ABNF, the character set for which is Unicode. [ABNF]

script        = outer *( comment-open inner comment-close outer )

outer         = < any string that doesn't contain a substring that matches not-in-outer >
not-in-outer  = comment-open
inner         = < any string that doesn't contain a substring that matches not-in-inner >
not-in-inner  = comment-close / script-open

comment-open  = "<!--"
comment-close = "-->"
script-open   = "<" s c r i p t tag-end

s             =  %x0053 ; U+0053 LATIN CAPITAL LETTER S
s             =/ %x0073 ; U+0073 LATIN SMALL LETTER S
c             =  %x0043 ; U+0043 LATIN CAPITAL LETTER C
c             =/ %x0063 ; U+0063 LATIN SMALL LETTER C
r             =  %x0052 ; U+0052 LATIN CAPITAL LETTER R
r             =/ %x0072 ; U+0072 LATIN SMALL LETTER R
i             =  %x0049 ; U+0049 LATIN CAPITAL LETTER I
i             =/ %x0069 ; U+0069 LATIN SMALL LETTER I
p             =  %x0050 ; U+0050 LATIN CAPITAL LETTER P
p             =/ %x0070 ; U+0070 LATIN SMALL LETTER P
t             =  %x0054 ; U+0054 LATIN CAPITAL LETTER T
t             =/ %x0074 ; U+0074 LATIN SMALL LETTER T

tag-end       =  %x0009 ; U+0009 CHARACTER TABULATION (tab)
tag-end       =/ %x000A ; U+000A LINE FEED (LF)
tag-end       =/ %x000C ; U+000C FORM FEED (FF)
tag-end       =/ %x0020 ; U+0020 SPACE
tag-end       =/ %x002F ; U+002F SOLIDUS (/)
tag-end       =/ %x003E ; U+003E GREATER-THAN SIGN (>)

When a script element contains script documentation, there are further restrictions on the contents of the element, as described in the section below.

The following script illustrates this issue. Suppose you have a script that contains a string, as in:

const example = 'Consider this string: <!-- <script>';
console.log(example);

If one were to put this string directly in a script block, it would violate the restrictions above:

<script>
  const example = 'Consider this string: <!-- <script>';
  console.log(example);
</script>

The bigger problem, though, and the reason why it would violate those restrictions, is that actually the script would get parsed weirdly: the script block above is not terminated. That is, what looks like a "</script>" end tag in this snippet is actually still part of the script block. The script doesn't execute (since it's not terminated); if it somehow were to execute, as it might if the markup looked as follows, it would fail because the script (highlighted here) is not valid JavaScript:

<script>
  const example = 'Consider this string: <!-- <script>';
  console.log(example);
</script>
<!-- despite appearances, this is actually part of the script still! -->
<script>
 ... // this is the same script block still...
</script>

What is going on here is that for legacy reasons, "<!--" and "<script" strings in script elements in HTML need to be balanced in order for the parser to consider closing the block.

By escaping the problematic strings as mentioned at the top of this section, the problem is avoided entirely:

<script>
  // Note: `\x3C` is an escape sequence for `<`.
  const example = 'Consider this string: \x3C!-- \x3Cscript>';
  console.log(example);
</script>
<!-- this is just a comment between script blocks -->
<script>
 ... // this is a new script block
</script>

It is possible for these sequences to naturally occur in script expressions, as in the following examples:

if (x<!--y) { ... }
if ( player<script ) { ... }

In such cases the characters cannot be escaped, but the expressions can be rewritten so that the sequences don't occur, as in:

if (x < !--y) { ... }
if (!--y > x) { ... }
if (!(--y) > x) { ... }
if (player < script) { ... }
if (script > player) { ... }

Doing this also avoids a different pitfall as well: for related historical reasons, the string "<!--" in classic scripts is actually treated as a line comment start, just like "//".

4.12.1.4 Inline documentation for external scripts

If a script element's src attribute is specified, then the contents of the script element, if any, must be such that the value of the text IDL attribute, which is derived from the element's contents, matches the documentation production in the following ABNF, the character set for which is Unicode. [ABNF]

documentation = *( *( space / tab / comment ) [ line-comment ] newline )
comment       = slash star *( not-star / star not-slash ) 1*star slash
line-comment  = slash slash *not-newline

; characters
tab           = %x0009 ; U+0009 CHARACTER TABULATION (tab)
newline       = %x000A ; U+000A LINE FEED (LF)
space         = %x0020 ; U+0020 SPACE
star          = %x002A ; U+002A ASTERISK (*)
slash         = %x002F ; U+002F SOLIDUS (/)
not-newline   = %x0000-0009 / %x000B-10FFFF
                ; a scalar value other than U+000A LINE FEED (LF)
not-star      = %x0000-0029 / %x002B-10FFFF
                ; a scalar value other than U+002A ASTERISK (*)
not-slash     = %x0000-002E / %x0030-10FFFF
                ; a scalar value other than U+002F SOLIDUS (/)

This corresponds to putting the contents of the element in JavaScript comments.

This requirement is in addition to the earlier restrictions on the syntax of contents of script elements.

This allows authors to include documentation, such as license information or API information, inside their documents while still referring to external script files. The syntax is constrained so that authors don't accidentally include what looks like valid script while also providing a src attribute.

<script src="cool-effects.js">
 // create new instances using:
 //    var e = new Effect();
 // start the effect using .play, stop using .stop:
 //    e.play();
 //    e.stop();
</script>
4.12.1.5 Interaction of script elements and XSLT

This section is non-normative.

This specification does not define how XSLT interacts with the script element. However, in the absence of another specification actually defining this, here are some guidelines for implementers, based on existing implementations:

The main distinction between the first two cases and the last case is that the first two operate on Documents and the last operates on a fragment.

4.12.2 The noscript element

Element/noscript

Support in all current engines.

Firefox1+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+Internet ExplorerYes
Firefox Android4+Safari iOSYesChrome AndroidYesWebView AndroidYesSamsung InternetYesOpera AndroidYes
Categories:
Metadata content.
Flow content.
Phrasing content.
Contexts in which this element can be used:
In a head element of an HTML document, if there are no ancestor noscript elements.
Where phrasing content is expected in HTML documents, if there are no ancestor noscript elements.
Content model:
When scripting is disabled, in a head element: in any order, zero or more link elements, zero or more style elements, and zero or more meta elements.
When scripting is disabled, not in a head element: transparent, but there must be no noscript element descendants.
Otherwise: text that conforms to the requirements given in the prose.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
Accessibility considerations:
For authors.
For implementers.
DOM interface:
Uses HTMLElement.

The noscript element represents nothing if scripting is enabled, and represents its children if scripting is disabled. It is used to present different markup to user agents that support scripting and those that don't support scripting, by affecting how the document is parsed.

When used in HTML documents, the allowed content model is as follows:

In a head element, if scripting is disabled for the noscript element

The noscript element must contain only link, style, and meta elements.

In a head element, if scripting is enabled for the noscript element

The noscript element must contain only text, except that invoking the HTML fragment parsing algorithm with the noscript element as the context element and the text contents as the input must result in a list of nodes that consists only of link, style, and meta elements that would be conforming if they were children of the noscript element, and no parse errors.

Outside of head elements, if scripting is disabled for the noscript element

The noscript element's content model is transparent, with the additional restriction that a noscript element must not have a noscript element as an ancestor (that is, noscript can't be nested).

Outside of head elements, if scripting is enabled for the noscript element

The noscript element must contain only text, except that the text must be such that running the following algorithm results in a conforming document with no noscript elements and no script elements, and such that no step in the algorithm throws an exception or causes an HTML parser to flag a parse error:

  1. Remove every script element from the document.
  2. Make a list of every noscript element in the document. For every noscript element in that list, perform the following steps:
    1. Let s be the child text content of the noscript element.
    2. Set the outerHTML attribute of the noscript element to the value of s. (This, as a side-effect, causes the noscript element to be removed from the document.) [DOMPARSING]

All these contortions are required because, for historical reasons, the noscript element is handled differently by the HTML parser based on whether scripting was enabled or not when the parser was invoked.

The noscript element must not be used in XML documents.

The noscript element is only effective in the HTML syntax, it has no effect in the XML syntax. This is because the way it works is by essentially "turning off" the parser when scripts are enabled, so that the contents of the element are treated as pure text and not as real elements. XML does not define a mechanism by which to do this.

The noscript element has no other requirements. In particular, children of the noscript element are not exempt from form submission, scripting, and so forth, even when scripting is enabled for the element.

In the following example, a noscript element is used to provide fallback for a script.

<form action="calcSquare.php">
 <p>
  <label for=x>Number</label>:
  <input id="x" name="x" type="number">
 </p>
 <script>
  var x = document.getElementById('x');
  var output = document.createElement('p');
  output.textContent = 'Type a number; it will be squared right then!';
  x.form.appendChild(output);
  x.form.onsubmit = function () { return false; }
  x.oninput = function () {
    var v = x.valueAsNumber;
    output.textContent = v + ' squared is ' + v * v;
  };
 </script>
 <noscript>
  <input type=submit value="Calculate Square">
 </noscript>
</form>

When script is disabled, a button appears to do the calculation on the server side. When script is enabled, the value is computed on-the-fly instead.

The noscript element is a blunt instrument. Sometimes, scripts might be enabled, but for some reason the page's script might fail. For this reason, it's generally better to avoid using noscript, and to instead design the script to change the page from being a scriptless page to a scripted page on the fly, as in the next example:

<form action="calcSquare.php">
 <p>
  <label for=x>Number</label>:
  <input id="x" name="x" type="number">
 </p>
 <input id="submit" type=submit value="Calculate Square">
 <script>
  var x = document.getElementById('x');
  var output = document.createElement('p');
  output.textContent = 'Type a number; it will be squared right then!';
  x.form.appendChild(output);
  x.form.onsubmit = function () { return false; }
  x.oninput = function () {
    var v = x.valueAsNumber;
    output.textContent = v + ' squared is ' + v * v;
  };
  var submit = document.getElementById('submit');
  submit.parentNode.removeChild(submit);
 </script>
</form>

The above technique is also useful in XML documents, since noscript is not allowed there.

4.12.3 The template element

Element/template

Support in all current engines.

Firefox22+Safari8+Chrome26+
Opera15+Edge79+
Edge (Legacy)13+Internet ExplorerNo
Firefox Android22+Safari iOS8+Chrome Android26+WebView AndroidYesSamsung Internet1.5+Opera Android?

HTMLTemplateElement

Support in all current engines.

Firefox22+Safari8+Chrome26+
Opera15+Edge79+
Edge (Legacy)13+Internet ExplorerNo
Firefox Android22+Safari iOS8+Chrome Android26+WebView Android4.4+Samsung Internet1.5+Opera Android14+
Categories:
Metadata content.
Flow content.
Phrasing content.
Script-supporting element.
Contexts in which this element can be used:
Where metadata content is expected.
Where phrasing content is expected.
Where script-supporting elements are expected.
As a child of a colgroup element that doesn't have a span attribute.
Content model:
Nothing (for clarification, see example).
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
Accessibility considerations:
For authors.
For implementers.
DOM interface:
[Exposed=Window]
interface HTMLTemplateElement : HTMLElement {
  [HTMLConstructor] constructor();

  readonly attribute DocumentFragment content;
};

The template element is used to declare fragments of HTML that can be cloned and inserted in the document by script.

In a rendering, the template element represents nothing.

The template contents of a template element are not children of the element itself.

It is also possible, as a result of DOM manipulation, for a template element to contain template element's content model, since its content model is defined as nothing.

For example, consider the following document:

<!doctype html>
<html lang="en">
 <head>
  <title>Homework</title>
 <body>
  <template id="template"><p>Smile!</p></template>
  <script>
   let num = 3;
   const fragment = document.getElementById('template').content.cloneNode(true);
   while (num-- > 1) {
     fragment.firstChild.before(fragment.firstChild.cloneNode(true));
     fragment.firstChild.textContent += fragment.lastChild.textContent;
   }
   document.body.appendChild(fragment);
  </script>
</html>

The p element in the template is not a child of the template in the DOM; it is a child of the template element's content IDL attribute.

If the script were to call on the template element, that would add a child to the template element (as for any other element); however, doing so is a violation of the template element's content model.

template.content

HTMLTemplateElement/content

Support in all current engines.

Firefox22+Safari8+Chrome26+
Opera15+Edge79+
Edge (Legacy)13+Internet ExplorerNo
Firefox Android22+Safari iOS8+Chrome Android26+WebView Android4.4+Samsung Internet1.5+Opera Android14+

Returns the template contents (a

Each template element has an associated template contents. The template contents have no conformance requirements. When a template element is created, the user agent must run the following steps to establish the template contents:

  1. Let doc be the template element's node document's appropriate template contents owner document.

  2. Create a node document is doc and host is the template element.

  3. Set the template element's template contents to the newly created

    A Document doc's appropriate template contents owner document is the Document returned by the following algorithm:

    1. If doc is not a Document created by this algorithm, then:

      1. If doc does not yet have an associated inert template document, then:

        1. Let new doc be a new Document (whose browsing context is null). This is "a Document created by this algorithm" for the purposes of the step above.

        2. If doc is an HTML document, mark new doc as an HTML document also.

        3. Let doc's associated inert template document be new doc.

      2. Set doc to doc's associated inert template document.

      Each Document not created by this algorithm thus gets a single Document to act as its proxy for owning the template contents of all its template elements, so that they aren't in a browsing context and thus remain inert (e.g. scripts do not run). Meanwhile, template elements inside Document objects that are created by this algorithm just reuse the same Document owner for their contents.

    2. Return doc.

    The adopting steps (with node and oldDocument as parameters) for template elements are the following:

    1. Let doc be node's node document's appropriate template contents owner document.

      node's node document is the Document object that node was just adopted into.

    2. Adopt node's template contents (a doc.

    The content IDL attribute must return the template element's template contents.


    The cloning steps for a template element node being cloned to a copy copy must run the following steps:

    1. If the clone children flag is not set in the calling clone algorithm, return.

    2. Let copied contents be the result of cloning all the children of node's template contents, with document set to copy's template contents's node document, and with the clone children flag set.

    3. Append copied contents to copy's template contents.

    In this example, a script populates a table four-column with data from a data structure, using a template to provide the element structure instead of manually generating the structure from markup.

    <!DOCTYPE html>
    <html lang='en'>
    <title>Cat data</title>
    <script>
     // Data is hard-coded here, but could come from the server
     var data = [
       { name: 'Pillar', color: 'Ticked Tabby', sex: 'Female (neutered)', legs: 3 },
       { name: 'Hedral', color: 'Tuxedo', sex: 'Male (neutered)', legs: 4 },
     ];
    </script>
    <table>
     <thead>
      <tr>
       <th>Name <th>Color <th>Sex <th>Legs
     <tbody>
      <template id="row">
       <tr><td><td><td><td>
      </template>
    </table>
    <script>
     var template = document.querySelector('#row');
     for (var i = 0; i < data.length; i += 1) {
       var cat = data[i];
       var clone = template.content.cloneNode(true);
       var cells = clone.querySelectorAll('td');
       cells[0].textContent = cat.name;
       cells[1].textContent = cat.color;
       cells[2].textContent = cat.sex;
       cells[3].textContent = cat.legs;
       template.parentNode.appendChild(clone);
     }
    </script>

    This example uses on the template's contents; it could equivalently have used , which does the same thing. The only difference between these two APIs is when the node document is updated: with it is updated when the nodes are appended with , with it is updated when the nodes are cloned.

    4.12.3.1 Interaction of template elements with XSLT and XPath

    This section is non-normative.

    This specification does not define how XSLT and XPath interact with the template element. However, in the absence of another specification actually defining this, here are some guidelines for implementers, which are intended to be consistent with other processing described in this specification:

    4.12.4 The slot element

    Element/slot

    Support in all current engines.

    Firefox63+Safari10+Chrome53+
    Opera40+Edge79+
    Edge (Legacy)NoInternet ExplorerNo
    Firefox Android63+Safari iOS10+Chrome Android53+WebView Android53+Samsung Internet6.0+Opera Android41+

    HTMLSlotElement

    Support in all current engines.

    Firefox63+Safari10+Chrome53+
    Opera40+Edge79+
    Edge (Legacy)NoInternet ExplorerNo
    Firefox Android63+Safari iOS10+Chrome Android53+WebView Android53+Samsung Internet6.0+Opera Android41+
    Categories:
    Flow content.
    Phrasing content.
    Contexts in which this element can be used:
    Where phrasing content is expected.
    Content model:
    Transparent
    Tag omission in text/html:
    Neither tag is omissible.
    Content attributes:
    Global attributes
    name — Name of shadow tree slot
    Accessibility considerations:
    For authors.
    For implementers.
    DOM interface:
    [Exposed=Window]
    interface HTMLSlotElement : HTMLElement {
      [HTMLConstructor] constructor();
    
      [CEReactions] attribute DOMString name;
      sequence<Node> assignedNodes(optional AssignedNodesOptions options = {});
      sequence<Element> assignedElements(optional AssignedNodesOptions options = {});
      undefined assign((Element or Text)... nodes);
    };
    
    dictionary AssignedNodesOptions {
      boolean flatten = false;
    };

    The slot element defines a slot. It is typically used in a shadow tree. A slot element represents its assigned nodes, if any, and its contents otherwise.

    The name content attribute may contain any string value. It represents a slot's name.

    The name attribute is used to assign slots to other elements: a slot element with a name attribute creates a named slot to which any element is assigned if that element has a slot attribute whose value matches that name attribute's value, and the slot element is a child of the shadow tree whose root's host has that corresponding slot attribute value.

    slot.name

    HTMLSlotElement/name

    Support in all current engines.

    Firefox63+Safari10+Chrome53+
    Opera40+Edge79+
    Edge (Legacy)NoInternet ExplorerNo
    Firefox Android63+Safari iOS10+Chrome Android53+WebView Android53+Samsung Internet6.0+Opera Android41+
    Can be used to get and set slot's name.
    slot.assignedNodes()

    HTMLSlotElement/assignedNodes

    Support in all current engines.

    Firefox63+Safari10+Chrome53+
    Opera40+Edge79+
    Edge (Legacy)NoInternet ExplorerNo
    Firefox Android63+Safari iOS10+Chrome Android53+WebView Android53+Samsung Internet6.0+Opera Android41+
    Returns slot's assigned nodes.
    slot.assignedNodes({ flatten: true })
    Returns slot's assigned nodes, if any, and slot's children otherwise, and does the same for any slot elements encountered therein, recursively, until there are no slot elements left.
    slot.assignedElements()

    HTMLSlotElement/assignedElements

    Support in all current engines.

    Firefox66+Safari12.1+Chrome65+
    Opera52+Edge79+
    Edge (Legacy)NoInternet ExplorerNo
    Firefox Android66+Safari iOS12.2+Chrome Android65+WebView Android65+Samsung Internet9.0+Opera Android47+
    Returns slot's assigned nodes, limited to elements.
    slot.assignedElements({ flatten: true })
    Returns the same as assignedNodes({ flatten: true }), limited to elements.
    slot.assign(...nodes)

    Sets slot's manually assigned nodes to the given nodes.

    The name IDL attribute must reflect the content attribute of the same name.

    The slot element has manually assigned nodes, which is an ordered set of slottables set by assign(). This set is initially empty.

    The manually assigned nodes set can be implemented using weak references to the slottables, because this set is not directly accessible from script.

    The assignedNodes(options) method steps are:

    1. If options["flatten"] is false, then return this's assigned nodes.

    2. Return the result of finding flattened slottables with this.

    The assignedElements(options) method steps are:

    1. If options["flatten"] is false, then return this's assigned nodes, filtered to contain only

      Return the result of finding flattened slottables with this, filtered to contain only

      HTMLSlotElement/assign

      Firefox92+SafariNoChrome86+
      Opera72+Edge86+
      Edge (Legacy)NoInternet ExplorerNo
      Firefox Android92+Safari iOSNoChrome Android86+WebView Android86+Samsung Internet14.0+Opera Android61+

      The assign(...nodes) method steps are:

      1. For each node of this's manually assigned nodes, set node's manual slot assignment to null.

      2. Let nodesSet be a new ordered set.

      3. For each node of nodes:

        1. If node's manual slot assignment refers to a slot, then remove node from that slot's manually assigned nodes.

        2. Set node's manual slot assignment to this.

        3. Append node to nodesSet.

      4. Set this's manually assigned nodes to nodesSet.

      5. Run assign slottables for a tree for this's root.